@linxiraos/pi-utils 1.0.0

package/dist/types/binary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Classify an in-memory byte header as binary (non-UTF-8-text).
+ *
+ * Binary when the header contains a NUL byte (true binary, plus UTF-16/UTF-32
+ * text whose ASCII range is NUL-padded) or when it is not valid UTF-8. The
+ * decode runs in streaming mode so a multibyte sequence truncated at the header
+ * boundary is tolerated, while any genuinely invalid byte still fails — matching
+ * the strict `fatal` decode the `local://`/`ssh://` read paths already use.
+ */
+export declare function isProbablyBinaryHeader(header: Uint8Array): boolean;
+/**
+ * Sniff the first {@link BINARY_SNIFF_BYTES} of `filePath` and report whether it
+ * is binary (non-UTF-8-text). See {@link isProbablyBinaryHeader} for the rule.
+ */
+export declare function isProbablyBinary(filePath: string, maxBytes?: number): Promise<boolean>;
+/** Synchronous {@link isProbablyBinary}. */
+export declare function isProbablyBinarySync(filePath: string, maxBytes?: number): boolean;

package/dist/types/browsers.d.ts

@@ -0,0 +1,68 @@
+/** Behavior-compatible reimplementation of @puppeteer/browsers' used surface. */
+/** Supported browser products. */
+export declare enum Browser {
+    CHROME = "chrome",
+    CHROMEHEADLESSSHELL = "chrome-headless-shell",
+    CHROMIUM = "chromium",
+    FIREFOX = "firefox",
+    CHROMEDRIVER = "chromedriver"
+}
+/** Browser download platform identifiers. */
+export declare enum BrowserPlatform {
+    LINUX = "linux",
+    LINUX_ARM = "linux_arm",
+    MAC = "mac",
+    MAC_ARM = "mac_arm",
+    WIN32 = "win32",
+    WIN64 = "win64"
+}
+/** Chrome-for-Testing release channel tags accepted by {@link resolveBuildId}. */
+export declare enum BrowserTag {
+    CANARY = "canary",
+    NIGHTLY = "nightly",
+    BETA = "beta",
+    DEV = "dev",
+    DEVEDITION = "devedition",
+    STABLE = "stable",
+    ESR = "esr",
+    LATEST = "latest"
+}
+/** Download progress reported while a browser archive is streamed to disk. */
+export interface BrowserDownloadProgress {
+    downloadedBytes: number;
+    totalBytes: number;
+}
+/** Inputs used to locate an installed browser executable. */
+export interface ComputeExecutablePathOptions {
+    browser: Browser;
+    buildId: string;
+    cacheDir: string;
+    platform?: BrowserPlatform;
+}
+/** Inputs used to download and install a browser. */
+export interface InstallOptions extends ComputeExecutablePathOptions {
+    baseUrl?: string;
+    downloadProgressCallback?: (progress: BrowserDownloadProgress) => void;
+}
+/** Metadata for one browser installation found in a Puppeteer cache. */
+export interface InstalledBrowser {
+    browser: Browser;
+    buildId: string;
+    platform: BrowserPlatform;
+    path: string;
+    executablePath: string;
+}
+/** Detect the current host's Puppeteer browser platform. */
+export declare function detectBrowserPlatform(): BrowserPlatform | undefined;
+/** Resolve a Chrome-for-Testing channel, milestone, or build prefix to a full build ID. */
+export declare function resolveBuildId(browser: Browser, _platform: BrowserPlatform, tag: string | BrowserTag): Promise<string>;
+/** Return the Chrome-for-Testing archive URL for a browser build. */
+export declare function getDownloadUrl(browser: Browser, platform: BrowserPlatform, buildId: string, baseUrl?: string): URL;
+/** Compute the executable path in Puppeteer's cache layout. */
+export declare function computeExecutablePath(options: ComputeExecutablePathOptions): string;
+/** Scan a Puppeteer cache for browser installation directories. */
+export declare function getInstalledBrowsers(options: {
+    cacheDir: string;
+}): Promise<InstalledBrowser[]>;
+/** Download and unpack Chrome into Puppeteer's existing cache layout. */
+export declare function install(options: InstallOptions): Promise<InstalledBrowser>;

package/dist/types/chalk.d.ts

@@ -0,0 +1,125 @@
+/** Behavior-compatible reimplementation of chalk's used surface. */
+/** ANSI color capability level. */
+export type ColorLevel = 0 | 1 | 2 | 3;
+/** Details about a terminal's supported color depth. */
+export interface ColorSupport {
+    /** Highest supported ANSI color level. */
+    level: ColorLevel;
+    /** Whether the terminal supports the basic 16 colors. */
+    hasBasic: boolean;
+    /** Whether the terminal supports the 256-color palette. */
+    has256: boolean;
+    /** Whether the terminal supports 24-bit color. */
+    has16m: boolean;
+}
+interface ChalkOptions {
+    level?: ColorLevel;
+}
+/** A callable, chainable ANSI text formatter. */
+export interface ChalkInstance {
+    (...text: unknown[]): string;
+    /** Active color capability level. */
+    level: ColorLevel;
+    /** Reset every active terminal style. */
+    readonly reset: ChalkInstance;
+    /** Render bold text. */
+    readonly bold: ChalkInstance;
+    /** Render faint text. */
+    readonly dim: ChalkInstance;
+    /** Render italic text. */
+    readonly italic: ChalkInstance;
+    /** Render underlined text. */
+    readonly underline: ChalkInstance;
+    /** Swap foreground and background colors. */
+    readonly inverse: ChalkInstance;
+    /** Render struck-through text. */
+    readonly strikethrough: ChalkInstance;
+    /** Render black text. */
+    readonly black: ChalkInstance;
+    /** Render red text. */
+    readonly red: ChalkInstance;
+    /** Render green text. */
+    readonly green: ChalkInstance;
+    /** Render yellow text. */
+    readonly yellow: ChalkInstance;
+    /** Render blue text. */
+    readonly blue: ChalkInstance;
+    /** Render magenta text. */
+    readonly magenta: ChalkInstance;
+    /** Render cyan text. */
+    readonly cyan: ChalkInstance;
+    /** Render white text. */
+    readonly white: ChalkInstance;
+    /** Render gray text. */
+    readonly gray: ChalkInstance;
+    /** Alias for gray text. */
+    readonly grey: ChalkInstance;
+    /** Render bright black text. */
+    readonly blackBright: ChalkInstance;
+    /** Render bright red text. */
+    readonly redBright: ChalkInstance;
+    /** Render bright green text. */
+    readonly greenBright: ChalkInstance;
+    /** Render bright yellow text. */
+    readonly yellowBright: ChalkInstance;
+    /** Render bright blue text. */
+    readonly blueBright: ChalkInstance;
+    /** Render bright magenta text. */
+    readonly magentaBright: ChalkInstance;
+    /** Render bright cyan text. */
+    readonly cyanBright: ChalkInstance;
+    /** Render bright white text. */
+    readonly whiteBright: ChalkInstance;
+    /** Render text on a black background. */
+    readonly bgBlack: ChalkInstance;
+    /** Render text on a red background. */
+    readonly bgRed: ChalkInstance;
+    /** Render text on a green background. */
+    readonly bgGreen: ChalkInstance;
+    /** Render text on a yellow background. */
+    readonly bgYellow: ChalkInstance;
+    /** Render text on a blue background. */
+    readonly bgBlue: ChalkInstance;
+    /** Render text on a magenta background. */
+    readonly bgMagenta: ChalkInstance;
+    /** Render text on a cyan background. */
+    readonly bgCyan: ChalkInstance;
+    /** Render text on a white background. */
+    readonly bgWhite: ChalkInstance;
+    /** Render text on a gray background. */
+    readonly bgGray: ChalkInstance;
+    /** Alias for a gray background. */
+    readonly bgGrey: ChalkInstance;
+    /** Render text on a bright black background. */
+    readonly bgBlackBright: ChalkInstance;
+    /** Render text on a bright red background. */
+    readonly bgRedBright: ChalkInstance;
+    /** Render text on a bright green background. */
+    readonly bgGreenBright: ChalkInstance;
+    /** Render text on a bright yellow background. */
+    readonly bgYellowBright: ChalkInstance;
+    /** Render text on a bright blue background. */
+    readonly bgBlueBright: ChalkInstance;
+    /** Render text on a bright magenta background. */
+    readonly bgMagentaBright: ChalkInstance;
+    /** Render text on a bright cyan background. */
+    readonly bgCyanBright: ChalkInstance;
+    /** Render text on a bright white background. */
+    readonly bgWhiteBright: ChalkInstance;
+    /** Render text with an arbitrary hexadecimal foreground color. */
+    hex(color: string): ChalkInstance;
+}
+/** Constructor for an independently configured chalk formatter. */
+export interface ChalkConstructor {
+    new (options?: ChalkOptions): ChalkInstance;
+}
+/** Detect an ANSI color level from terminal environment and TTY state. */
+export declare function detectColorLevel(environment: NodeJS.ProcessEnv, isTTY: boolean): ColorLevel;
+/** Color support detected for standard output. */
+export declare const supportsColor: false | ColorSupport;
+/** Color support detected for standard error. */
+export declare const supportsColorStderr: false | ColorSupport;
+/** Construct an independently configured chalk formatter. */
+export declare const Chalk: ChalkConstructor;
+declare const chalk: ChalkInstance;
+export default chalk;

package/dist/types/cli.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A user-facing argument/flag validation failure. Thrown by {@link Command.parse}
+ * for missing/invalid positionals and flags. The top-level {@link run} handler
+ * prints its message plus the command usage line to stderr and exits 1, instead
+ * of letting it bubble to the process-level catch — which would dump a minified
+ * `dist/cli.js` code frame over a plain argument mistake (issue #5369).
+ */
+export declare class CliUsageError extends Error {
+    constructor(message: string);
+}
+export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "string" | "boolean" | "integer"> {
+    kind: K;
+    description?: string;
+    char?: string;
+    default?: unknown;
+    multiple?: boolean;
+    options?: readonly string[];
+    required?: boolean;
+}
+export interface ArgDescriptor {
+    kind: "string";
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    options?: readonly string[];
+}
+interface FlagInput {
+    description?: string;
+    char?: string;
+    default?: unknown;
+    multiple?: boolean;
+    options?: readonly string[];
+    required?: boolean;
+}
+interface ArgInput {
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    options?: readonly string[];
+}
+/** Builders that match the `Flags.*()` / `Args.*()` API from oclif. */
+export declare const Flags: {
+    string<T extends FlagInput>(opts?: T): FlagDescriptor<"string"> & T;
+    boolean<T extends FlagInput>(opts?: T): FlagDescriptor<"boolean"> & T;
+    integer<T extends FlagInput & {
+        default?: number;
+    }>(opts?: T): FlagDescriptor<"integer"> & T;
+};
+export declare const Args: {
+    string<T extends ArgInput>(opts?: T): ArgDescriptor & T;
+};
+type FlagValue<D extends FlagDescriptor> = D["kind"] extends "boolean" ? D extends {
+    default: boolean;
+} ? boolean : boolean | undefined : D["kind"] extends "integer" ? D extends {
+    default: number;
+} ? number : number | undefined : D extends {
+    multiple: true;
+} ? string[] | undefined : string | undefined;
+type ArgValue<D extends ArgDescriptor> = D extends {
+    multiple: true;
+} ? string[] | undefined : string | undefined;
+type FlagValues<T extends Record<string, FlagDescriptor>> = {
+    [K in keyof T]: FlagValue<T[K]>;
+};
+type ArgValues<T extends Record<string, ArgDescriptor>> = {
+    [K in keyof T]: ArgValue<T[K]>;
+};
+export interface ParseOutput<F extends Record<string, FlagDescriptor> = Record<string, FlagDescriptor>, A extends Record<string, ArgDescriptor> = Record<string, ArgDescriptor>> {
+    flags: FlagValues<F>;
+    args: ArgValues<A>;
+    argv: string[];
+}
+export interface CommandMetadata {
+    description?: string;
+    hidden?: boolean;
+    flags?: Record<string, FlagDescriptor>;
+    args?: Record<string, ArgDescriptor>;
+    examples?: string[];
+}
+export interface CommandCtor extends CommandMetadata {
+    new (argv: string[], config: CliConfig): Command;
+    strict?: boolean;
+    aliases?: string[];
+}
+/** Configuration passed to every command instance and help renderers. */
+export interface CliConfig<TCommand extends CommandMetadata = CommandCtor> {
+    bin: string;
+    version: string;
+    /** All registered commands keyed by their canonical name. */
+    commands: Map<string, TCommand>;
+}
+/** Minimal Command base matching the oclif surface we use. */
+export declare abstract class Command {
+    argv: string[];
+    config: CliConfig;
+    constructor(argv: string[], config: CliConfig);
+    abstract run(): Promise<void>;
+    /**
+     * Parse argv against the static `flags` and `args` declared on the
+     * concrete command class. Returns a typed `{ flags, args, argv }` object.
+     */
+    parse<C extends CommandCtor>(_Cmd: C): Promise<ParseOutput<NonNullable<C["flags"]> extends Record<string, FlagDescriptor> ? NonNullable<C["flags"]> : Record<string, FlagDescriptor>, NonNullable<C["args"]> extends Record<string, ArgDescriptor> ? NonNullable<C["args"]> : Record<string, ArgDescriptor>>>;
+}
+/** Render full root help: header, default command details, subcommand list. */
+export declare function renderRootHelp(config: CliConfig<CommandMetadata>): void;
+/** Build the single USAGE line for a command (without the leading label). */
+export declare function commandUsageLine(bin: string, id: string, Cmd: CommandCtor): string;
+/** Render help for a single command. */
+export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void;
+/** A lazily-loaded command: canonical name, loader, and optional aliases. */
+export interface CommandEntry {
+    name: string;
+    load: () => Promise<CommandCtor>;
+    help?: CommandMetadata;
+    aliases?: string[];
+}
+export interface RunOptions {
+    bin: string;
+    version: string;
+    argv: string[];
+    commands: CommandEntry[];
+    /** Custom help renderer with the fully loaded command constructors. */
+    help?: (config: CliConfig) => Promise<void> | void;
+    /** Lightweight help renderer backed by static command metadata. */
+    metadataHelp?: (config: CliConfig<CommandMetadata>) => Promise<void> | void;
+}
+/**
+ * Main entry point — replaces `run()` from @oclif/core.
+ *
+ * Each command is explicitly registered with a lazy loader.
+ * No filesystem scanning, no plugin system, no package.json reading.
+ */
+export declare function run(opts: RunOptions): Promise<void>;
+export {};

package/dist/types/color.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Color manipulation utilities for hex colors.
+ *
+ * @example
+ * ```ts
+ * import { hexToHsv, hsvToHex } from "@linxiraos/pi-utils";
+ *
+ * // Rotate the hue by 90°
+ * const hsv = hexToHsv("#4ade80");
+ * hsv.h = (hsv.h + 90) % 360;
+ * const newHex = hsvToHex(hsv);
+ * ```
+ */
+export interface HSV {
+    /** Hue in degrees (0-360) */
+    h: number;
+    /** Saturation (0-1) */
+    s: number;
+    /** Value/brightness (0-1) */
+    v: number;
+}
+export interface RGB {
+    /** Red (0-255) */
+    r: number;
+    /** Green (0-255) */
+    g: number;
+    /** Blue (0-255) */
+    b: number;
+}
+/**
+ * Parse a hex color string to RGB.
+ * Supports #RGB, #RRGGBB formats.
+ */
+export declare function hexToRgb(hex: string): RGB;
+/**
+ * Convert RGB to hex color string.
+ */
+export declare function rgbToHex(rgb: RGB): string;
+/**
+ * Convert RGB to HSV.
+ */
+export declare function rgbToHsv(rgb: RGB): HSV;
+/**
+ * Convert HSV to RGB.
+ */
+export declare function hsvToRgb(hsv: HSV): RGB;
+/**
+ * Convert hex color to HSV.
+ */
+export declare function hexToHsv(hex: string): HSV;
+/**
+ * Convert HSV to hex color.
+ */
+export declare function hsvToHex(hsv: HSV): string;
+/**
+ * Shift the hue of a hex color by a given number of degrees.
+ */
+export declare function shiftHue(hex: string, degrees: number): string;
+export interface HSVAdjustment {
+    /** Hue shift in degrees (additive) */
+    h?: number;
+    /** Saturation multiplier */
+    s?: number;
+    /** Value/brightness multiplier */
+    v?: number;
+}
+/**
+ * Adjust HSV components of a hex color.
+ *
+ * @param hex - Hex color string (#RGB or #RRGGBB)
+ * @param adj - Adjustments: h is additive degrees, s and v are multipliers
+ * @returns New hex color string
+ *
+ * @example
+ * ```ts
+ * // Shift hue +60°, reduce saturation to 71%
+ * adjustHsv("#00ff88", { h: 60, s: 0.71 }) // "#4a9eff"
+ * ```
+ */
+export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;
+/**
+ * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
+ */
+export declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ *
+ * Cheap and good enough for a light/dark *classification* threshold. NOT suitable
+ * for contrast ratios — use {@link relativeLuminance} for those.
+ */
+export declare function colorLuma(value: string | number): number | undefined;
+/**
+ * WCAG 2.x relative luminance (BT.709 weights over linearized sRGB), normalized to
+ * 0..1. This is the value the WCAG contrast-ratio formula expects.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ */
+export declare function relativeLuminance(value: string | number): number | undefined;

package/dist/types/dates.d.ts

@@ -0,0 +1,7 @@
+/** Behavior-compatible reimplementation of date-fns's used surface. */
+/** Format a date with the supported date-fns v4 tokens and quoted literals. */
+export declare function format(value: Date | number, pattern: string): string;
+/** Describe the distance from a date to now using date-fns's English thresholds. */
+export declare function formatDistanceToNow(value: Date | number, options?: {
+    addSuffix?: boolean;
+}): string;