@linxiraos/pi-utils 1.0.0

package/dist/types/vendor/mermaid-ascii/types.d.ts

@@ -0,0 +1,114 @@
+export interface MermaidGraph {
+    direction: Direction;
+    nodes: Map<string, MermaidNode>;
+    edges: MermaidEdge[];
+    subgraphs: MermaidSubgraph[];
+    classDefs: Map<string, Record<string, string>>;
+    /** Maps node IDs to their class names (from `class X className` or `:::className` shorthand) */
+    classAssignments: Map<string, string>;
+    /** Maps node IDs to inline styles (from `style X fill:#f00,stroke:#333`) */
+    nodeStyles: Map<string, Record<string, string>>;
+    /** Maps edge indices (or 'default') to inline styles from `linkStyle` directives */
+    linkStyles: Map<number | 'default', Record<string, string>>;
+}
+export type Direction = 'TD' | 'TB' | 'LR' | 'BT' | 'RL';
+export interface MermaidNode {
+    id: string;
+    label: string;
+    shape: NodeShape;
+}
+export type NodeShape = 'rectangle' | 'rounded' | 'diamond' | 'stadium' | 'circle' | 'subroutine' | 'doublecircle' | 'hexagon' | 'cylinder' | 'asymmetric' | 'trapezoid' | 'trapezoid-alt' | 'state-start' | 'state-end';
+export interface MermaidEdge {
+    source: string;
+    target: string;
+    label?: string;
+    style: EdgeStyle;
+    /** Whether to render an arrowhead at the start (source end) of the edge */
+    hasArrowStart: boolean;
+    /** Whether to render an arrowhead at the end (target end) of the edge */
+    hasArrowEnd: boolean;
+}
+export type EdgeStyle = 'solid' | 'dotted' | 'thick';
+export interface MermaidSubgraph {
+    id: string;
+    label: string;
+    nodeIds: string[];
+    children: MermaidSubgraph[];
+    /** Optional direction override for this subgraph's internal layout */
+    direction?: Direction;
+}
+export interface PositionedGraph {
+    width: number;
+    height: number;
+    nodes: PositionedNode[];
+    edges: PositionedEdge[];
+    groups: PositionedGroup[];
+}
+export interface PositionedNode {
+    id: string;
+    label: string;
+    shape: NodeShape;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Inline styles resolved from classDef + explicit `style` statements — override theme defaults */
+    inlineStyle?: Record<string, string>;
+}
+export interface PositionedEdge {
+    source: string;
+    target: string;
+    label?: string;
+    style: EdgeStyle;
+    hasArrowStart: boolean;
+    hasArrowEnd: boolean;
+    /** Full path including bends — array of {x, y} points */
+    points: Point[];
+    /** Layout-computed label center position (avoids label-label collisions) */
+    labelPosition?: Point;
+    /** Inline styles resolved from `linkStyle` directives — override theme defaults */
+    inlineStyle?: Record<string, string>;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface PositionedGroup {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    children: PositionedGroup[];
+}
+export interface RenderOptions {
+    /** Background color → CSS variable --bg. Default: '#FFFFFF' */
+    bg?: string;
+    /** Foreground / primary text color → CSS variable --fg. Default: '#27272A' */
+    fg?: string;
+    /** Edge/connector color → CSS variable --line */
+    line?: string;
+    /** Arrow heads, highlights → CSS variable --accent */
+    accent?: string;
+    /** Secondary text, edge labels → CSS variable --muted */
+    muted?: string;
+    /** Node/box fill tint → CSS variable --surface */
+    surface?: string;
+    /** Node/group stroke color → CSS variable --border */
+    border?: string;
+    /** Font family for all text. Default: 'Inter' */
+    font?: string;
+    /** Canvas padding in px. Default: 40 */
+    padding?: number;
+    /** Horizontal spacing between sibling nodes. Default: 24 */
+    nodeSpacing?: number;
+    /** Vertical spacing between layers. Default: 40 */
+    layerSpacing?: number;
+    /** Spacing between disconnected components. Default: nodeSpacing (24) */
+    componentSpacing?: number;
+    /** Render with transparent background (no background style on SVG). Default: false */
+    transparent?: boolean;
+    /** Enable hover tooltips on chart data points (xychart only). Default: false */
+    interactive?: boolean;
+}

package/dist/types/vendor/mermaid-ascii/xychart/colors.d.ts

@@ -0,0 +1,25 @@
+/** Default accent for charts when the theme doesn't provide one. */
+export declare const CHART_ACCENT_FALLBACK = "#3b82f6";
+/** Check whether a string is a valid 6-digit hex color (e.g. "#3b82f6"). */
+export declare function isValidHex(color: string): boolean;
+/**
+ * Detect whether a background color is dark (lightness < 50%).
+ */
+export declare function isDarkBackground(bgHex: string): boolean;
+/**
+ * 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 declare function mixHexColors(bgHex: string, fgHex: string, ratio: number): string;
+/**
+ * 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 declare function getSeriesColor(index: number, accentColor: string, bgColor?: string): string;

package/dist/types/vendor/mermaid-ascii/xychart/parser.d.ts

@@ -0,0 +1,6 @@
+import type { XYChart } from './types.js';
+/**
+ * Parse a Mermaid xychart-beta diagram from preprocessed lines.
+ * Lines should already be trimmed and comment-stripped.
+ */
+export declare function parseXYChart(lines: string[]): XYChart;

package/dist/types/vendor/mermaid-ascii/xychart/types.d.ts

@@ -0,0 +1,145 @@
+/** 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[];
+}
+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/dist/types/version.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Compare two version strings.
+ *
+ * Canonical comparator that supersedes the historical in-repo copies
+ * (update-cli, hackage scraper, release scripts):
+ * - inputs are trimmed and at most one leading `v`/`V` is stripped
+ * - dot-separated segments are compared numerically, missing trailing
+ *   segments count as 0, so `1.2` === `1.2.0` and any segment count works
+ * - a SemVer-2.0 prerelease suffix sorts before the plain release
+ *   (`1.0.0-beta` < `1.0.0`); prerelease identifiers follow SemVer order
+ *   (numeric < alphanumeric, numeric compared by value, alphanumeric
+ *   compared lexically, longer sets of equal fields win)
+ * - SemVer build metadata begins at the first `+` and does not participate
+ *   in precedence; it is stripped before core/prerelease parsing
+ * - malformed numeric segments compare as 0 (`1.2.x` === `1.2.0`)
+ * - never throws; returns only -1 | 0 | 1
+ */
+export declare function compareVersions(a: string, b: string): number;

package/dist/types/vterm/buffer.d.ts

@@ -0,0 +1,99 @@
+/** Cell rendition tracked by the virtual terminal. */
+export interface CellAttributes {
+    bold: boolean;
+    dim: boolean;
+    italic: boolean;
+    underline: boolean;
+    inverse: boolean;
+    strikethrough: boolean;
+    overline: boolean;
+    fgMode: 0 | 1 | 2;
+    fg: number;
+    bgMode: 0 | 1 | 2;
+    bg: number;
+}
+/** A mutable terminal grid cell. */
+export interface CellData {
+    chars: string;
+    width: number;
+    attrs: CellAttributes;
+}
+/** Creates the default rendition. */
+export declare function defaultAttributes(): CellAttributes;
+/** Creates an empty cell with the supplied rendition. */
+export declare function blankCell(attrs?: CellAttributes): CellData;
+/** Proposed xterm-compatible cell readback object. */
+export declare class BufferCell {
+    #private;
+    /** Reuses this object for another grid cell. */
+    setFrom(cell: CellData): this;
+    /** Returns the grapheme stored in this cell. */
+    getChars(): string;
+    /** Returns the cell width, with zero denoting a wide-cell continuation. */
+    getWidth(): number;
+    /** Returns the packed foreground palette index or RGB value. */
+    getFgColor(): number;
+    /** Returns the packed background palette index or RGB value. */
+    getBgColor(): number;
+    /** Reports bold rendition. */
+    isBold(): number;
+    /** Reports dim rendition. */
+    isDim(): number;
+    /** Reports italic rendition. */
+    isItalic(): number;
+    /** Reports underline rendition. */
+    isUnderline(): number;
+    /** Reports inverse rendition. */
+    isInverse(): number;
+    /** Reports strikethrough rendition. */
+    isStrikethrough(): number;
+    /** Reports overline rendition. */
+    isOverline(): number;
+    /** Reports a true-color foreground. */
+    isFgRGB(): boolean;
+    /** Reports a true-color background. */
+    isBgRGB(): boolean;
+    /** Reports a palette foreground. */
+    isFgPalette(): boolean;
+    /** Reports a palette background. */
+    isBgPalette(): boolean;
+}
+/** One physical row in a terminal buffer. */
+export declare class BufferLine {
+    cells: CellData[];
+    isWrapped: boolean;
+    constructor(columns: number, attrs?: CellAttributes);
+    /** Number of grid columns in the line. */
+    get length(): number;
+    /** Reads a cell, optionally reusing the caller's object. */
+    getCell(column: number, cell?: BufferCell): BufferCell | undefined;
+    /** Converts a column range to text. */
+    translateToString(trimRight?: boolean, startColumn?: number, endColumn?: number): string;
+}
+/** Storage backing one terminal screen and its history. */
+export interface BufferState {
+    lines: BufferLine[];
+    baseY: number;
+    viewportY: number;
+    cursorX: number;
+    cursorY: number;
+}
+/** Public xterm-compatible view over a buffer state. */
+export declare class BufferView {
+    private readonly state;
+    constructor(state: () => BufferState);
+    /** Number of physical lines, including scrollback. */
+    get length(): number;
+    /** First row of the live screen in the full buffer. */
+    get baseY(): number;
+    /** First row currently exposed by the viewport. */
+    get viewportY(): number;
+    /** Cursor column in the live screen. */
+    get cursorX(): number;
+    /** Cursor row in the live screen. */
+    get cursorY(): number;
+    /** Reads a physical buffer line. */
+    getLine(row: number): BufferLine | undefined;
+    /** Creates a reusable empty cell readback object. */
+    getNullCell(): BufferCell;
+}

package/dist/types/vterm/terminal.d.ts

@@ -0,0 +1,44 @@
+import { BufferView } from "./buffer.js";
+/** Construction options supported by the headless virtual terminal. */
+export interface TerminalOptions {
+    cols?: number;
+    rows?: number;
+    scrollback?: number;
+    allowProposedApi?: boolean;
+    disableStdin?: boolean;
+}
+/** Disposable event subscription. */
+export interface Disposable {
+    dispose(): void;
+}
+/** Observable terminal modes used by interactive input normalization. */
+export interface TerminalModes {
+    applicationCursorKeysMode: boolean;
+}
+/** Buffer collection exposed by the virtual terminal. */
+export interface TerminalBuffers {
+    readonly active: BufferView;
+    readonly normal: BufferView;
+    readonly alternate: BufferView;
+}
+/** Behavior-compatible reimplementation of @xterm/headless's used surface. */
+export declare class Terminal {
+    #private;
+    /** Current terminal column count. */
+    cols: number;
+    /** Current terminal row count. */
+    rows: number;
+    /** Normal, alternate, and active buffer views. */
+    readonly buffer: TerminalBuffers;
+    /** Currently active input modes. */
+    readonly modes: TerminalModes;
+    constructor(options?: TerminalOptions);
+    /** Parses terminal output and invokes the callback after the write is committed. */
+    write(data: string | Uint8Array, callback?: () => void): void;
+    /** Changes the terminal grid and reflows wrapped normal-buffer lines. */
+    resize(columns: number, rows: number): void;
+    /** Subscribes to terminal-generated input replies. */
+    onData(listener: (data: string) => void): Disposable;
+    /** Releases parser state and event listeners. */
+    dispose(): void;
+}

package/dist/types/vterm.d.ts

@@ -0,0 +1,8 @@
+/** Behavior-compatible reimplementation of @xterm/headless's used surface. */
+export * from "./vterm/buffer.js";
+export * from "./vterm/terminal.js";
+import { Terminal } from "./vterm/terminal.js";
+declare const vterm: {
+    Terminal: typeof Terminal;
+};
+export default vterm;

package/dist/types/which.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cache policy for which lookups.
+ */
+export declare const enum WhichCachePolicy {
+    /**
+     * Use cached result if available.
+     */
+    Cached = 0,
+    /**
+     * Bypass cache and perform a new lookup.
+     */
+    Bypass = 1,
+    /**
+     * Always update cache.
+     */
+    Fresh = 2,
+    /**
+     * Read-only, serves from cache if present, but doesn't write.
+     */
+    ReadOnly = 3
+}
+export interface WhichOptions extends Bun.WhichOptions {
+    /**
+     * Cache policy for the lookup.
+     * Defaults to `WhichCachePolicy.Fresh`.
+     */
+    cache?: WhichCachePolicy;
+}
+export declare const whichFresh: typeof Bun.which;
+/**
+ * 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 declare function $which(command: string, options?: WhichOptions): string | null;

package/dist/types/worker-host.d.ts

@@ -0,0 +1,51 @@
+/** Prefix reserved for argv selectors dispatched by the shared CLI worker host. */
+export declare const WORKER_HOST_SELECTOR_PREFIX = "__omp_worker_";
+/** Whether an argv value selects a worker hosted by the shared CLI entrypoint. */
+export declare function isWorkerHostSelector(value: string | undefined): value is string;
+/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
+export declare function declareWorkerHostEntry(): void;
+/** Main-module path of the self-dispatching CLI host, or null outside it. */
+export declare function workerHostEntry(): string | null;
+/**
+ * Buffers messages a Bun worker thread receives before its real handler is
+ * attached, then hands them off once it is.
+ *
+ * Bun delivers messages the parent posted before the worker spawned exactly
+ * once — when the worker entry module's top-level evaluation completes — to the
+ * `message` listeners present at that moment. A worker whose handler attaches
+ * via a later `await import(...)` therefore misses that flush. The
+ * self-dispatching CLI host imports each worker module dynamically from inside
+ * its argv dispatch, so the worker's own `parentPort.on("message")` lands after
+ * the flush and the parent's synchronously-posted `init` handshake is dropped —
+ * every run then stalls until the init timeout fires and silently falls back to
+ * the inline worker (issue: eval cells always taking the full timeout).
+ *
+ * The host calls {@link installWorkerInbox} synchronously in the entry's sync
+ * prefix (before importing the worker module) so a `parentPort` listener exists
+ * at flush time; the worker module then {@link consumeWorkerInbox}es it and
+ * binds the real handler, replaying anything buffered. Re-dispatching through
+ * `parentPort.emit("message", …)` is not an option — Bun's port is an
+ * `EventTarget` whose `emit` throws — so the inbox calls the handler directly.
+ */
+export interface WorkerInbox {
+    /** Route buffered and subsequent messages to `handler`; returns an unbind fn. */
+    bind(handler: (message: unknown) => void): () => void;
+}
+/** Minimal `parentPort` surface the inbox needs (Node/Bun `MessagePort`). */
+interface MessageListenerPort {
+    on(event: "message", listener: (value: unknown) => void): unknown;
+}
+/**
+ * Attach a buffering `message` listener on `port` synchronously and stash the
+ * resulting inbox for the worker module to {@link consumeWorkerInbox}. MUST be
+ * called in the entry module's synchronous prefix — before the worker module is
+ * imported — so the listener exists when Bun flushes pre-spawn messages.
+ */
+export declare function installWorkerInbox(port: MessageListenerPort): WorkerInbox;
+/**
+ * Take the inbox installed by {@link installWorkerInbox} for this worker, or
+ * `null` when the worker module was loaded directly (no host pre-buffering, so
+ * the module's own synchronous top-level listener already wins the flush).
+ */
+export declare function consumeWorkerInbox(): WorkerInbox | null;
+export {};

package/dist/types/xml.d.ts

@@ -0,0 +1,31 @@
+/** Behavior-compatible reimplementation of fast-xml-parser's used surface. */
+/** Context supplied to an array-selection callback. */
+export type XMLArraySelector = (tagName: string, jPath: string, isLeafNode: boolean, isAttribute: boolean | null) => boolean;
+/** Options supported by {@link XMLParser}. */
+export interface XMLParserOptions {
+    /** Omits attributes when true (default). */
+    ignoreAttributes?: boolean;
+    /** Prefix applied to attribute property names. */
+    attributeNamePrefix?: string;
+    /** Property used for text alongside children or attributes. */
+    textNodeName?: string;
+    /** Trims ordinary text and attribute values. */
+    trimValues?: boolean;
+    /** Coerces numeric and boolean element text. */
+    parseTagValue?: boolean;
+    /** Coerces numeric and boolean attribute values. */
+    parseAttributeValue?: boolean;
+    /** Controls entity processing and its expansion ceiling. */
+    processEntities?: boolean | {
+        maxTotalExpansions?: number;
+    };
+    /** Selects element or attribute properties that must always be arrays. */
+    isArray?: XMLArraySelector;
+}
+/** Parses XML into the object shape used by the document converters. */
+export declare class XMLParser {
+    #private;
+    constructor(options?: XMLParserOptions);
+    /** Parses one XML document. */
+    parse(xml: string): unknown;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+	"type": "module",
+	"name": "@linxiraos/pi-utils",
+	"version": "1.0.0",
+	"description": "Shared utilities for pi packages",
+	"homepage": "https://linxira-os.github.io",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+		"directory": "packages/utils"
+	},
+	"bugs": {
+		"url": "https://github.com/can1357/oh-my-pi/issues"
+	},
+	"keywords": [
+		"utilities",
+		"cli",
+		"logging",
+		"streams"
+	],
+	"main": "./src/index.ts",
+	"types": "./dist/types/index.d.ts",
+	"scripts": {
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"lint": "biome lint .",
+		"test": "bun test --parallel",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@linxiraos/pi-natives": "1.0.0"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3.14"
+	},
+	"engines": {
+		"bun": ">=1.3.14"
+	},
+	"files": [
+		"src",
+		"README.md",
+		"CHANGELOG.md",
+		"dist/types"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./dist/types/*.d.ts",
+			"import": "./src/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}