notoken-core 1.0.0

package/dist/utils/platform.js

@@ -0,0 +1,253 @@
+/**
+ * OS/distro/platform detection.
+ *
+ * Detects:
+ * - Linux distro (Ubuntu, Debian, CentOS, RHEL, Fedora, Arch, Alpine, Amazon Linux)
+ * - macOS
+ * - Windows (PowerShell, cmd, WSL)
+ * - Package manager (apt, dnf, yum, pacman, apk, brew, choco)
+ * - Init system (systemd, sysvinit, openrc)
+ * - Shell (bash, zsh, fish, powershell, cmd)
+ *
+ * Works locally and remotely via SSH.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { platform as osPlatform, release as osRelease } from "node:os";
+let cachedLocal = null;
+/**
+ * Detect the local platform.
+ */
+export function detectLocalPlatform() {
+    if (cachedLocal)
+        return cachedLocal;
+    const os = osPlatform();
+    if (os === "win32") {
+        cachedLocal = detectWindows();
+    }
+    else if (os === "darwin") {
+        cachedLocal = detectMacOS();
+    }
+    else {
+        cachedLocal = detectLinux();
+    }
+    return cachedLocal;
+}
+function detectLinux() {
+    const kernel = osRelease();
+    const isWSL = kernel.toLowerCase().includes("microsoft") || kernel.toLowerCase().includes("wsl");
+    const arch = tryExec("uname -m") ?? "unknown";
+    const shell = process.env.SHELL ?? "unknown";
+    // Read /etc/os-release for distro info
+    let distro = "unknown";
+    let distroVersion = "";
+    let distroFamily = "unknown";
+    if (existsSync("/etc/os-release")) {
+        const content = readFileSync("/etc/os-release", "utf-8");
+        distro = extractField(content, "PRETTY_NAME") ?? extractField(content, "NAME") ?? "unknown";
+        distroVersion = extractField(content, "VERSION_ID") ?? "";
+        const id = (extractField(content, "ID") ?? "").toLowerCase();
+        const idLike = (extractField(content, "ID_LIKE") ?? "").toLowerCase();
+        if (id === "ubuntu" || id === "debian" || idLike.includes("debian")) {
+            distroFamily = "debian";
+        }
+        else if (id === "centos" || id === "rhel" || id === "fedora" || id === "rocky" || id === "alma" || id === "amzn" || idLike.includes("rhel") || idLike.includes("fedora")) {
+            distroFamily = "rhel";
+        }
+        else if (id === "arch" || idLike.includes("arch")) {
+            distroFamily = "arch";
+        }
+        else if (id === "alpine") {
+            distroFamily = "alpine";
+        }
+    }
+    // Detect package manager
+    let packageManager = "unknown";
+    if (commandExists("apt-get"))
+        packageManager = "apt";
+    else if (commandExists("dnf"))
+        packageManager = "dnf";
+    else if (commandExists("yum"))
+        packageManager = "yum";
+    else if (commandExists("pacman"))
+        packageManager = "pacman";
+    else if (commandExists("apk"))
+        packageManager = "apk";
+    // Detect init system
+    let initSystem = "unknown";
+    if (existsSync("/run/systemd/system") || commandExists("systemctl"))
+        initSystem = "systemd";
+    else if (existsSync("/etc/init.d"))
+        initSystem = "sysvinit";
+    else if (commandExists("rc-service"))
+        initSystem = "openrc";
+    return {
+        os: "linux",
+        distro,
+        distroVersion,
+        distroFamily,
+        kernel,
+        isWSL,
+        shell,
+        packageManager,
+        initSystem,
+        arch,
+    };
+}
+function detectMacOS() {
+    const version = tryExec("sw_vers -productVersion") ?? "";
+    return {
+        os: "darwin",
+        distro: `macOS ${version}`,
+        distroVersion: version,
+        distroFamily: "macos",
+        kernel: osRelease(),
+        isWSL: false,
+        shell: process.env.SHELL ?? "zsh",
+        packageManager: commandExists("brew") ? "brew" : "unknown",
+        initSystem: "launchd",
+        arch: tryExec("uname -m") ?? "unknown",
+    };
+}
+function detectWindows() {
+    const isPS = !!process.env.PSModulePath;
+    return {
+        os: "windows",
+        distro: `Windows ${osRelease()}`,
+        distroVersion: osRelease(),
+        distroFamily: "windows",
+        kernel: osRelease(),
+        isWSL: false,
+        shell: isPS ? "powershell" : "cmd",
+        packageManager: commandExists("choco") ? "choco" : "unknown",
+        initSystem: "unknown",
+        arch: process.arch,
+    };
+}
+/**
+ * Detect platform on a remote host via SSH.
+ */
+export async function detectRemotePlatform(environment) {
+    const { runRemoteCommand } = await import("../execution/ssh.js");
+    try {
+        const osRelease = await runRemoteCommand(environment, "cat /etc/os-release 2>/dev/null || echo 'UNKNOWN'");
+        const kernel = (await runRemoteCommand(environment, "uname -r")).trim();
+        const arch = (await runRemoteCommand(environment, "uname -m")).trim();
+        const shell = (await runRemoteCommand(environment, "echo $SHELL")).trim();
+        let distro = "unknown";
+        let distroVersion = "";
+        let distroFamily = "unknown";
+        if (!osRelease.includes("UNKNOWN")) {
+            distro = extractField(osRelease, "PRETTY_NAME") ?? "unknown";
+            distroVersion = extractField(osRelease, "VERSION_ID") ?? "";
+            const id = (extractField(osRelease, "ID") ?? "").toLowerCase();
+            const idLike = (extractField(osRelease, "ID_LIKE") ?? "").toLowerCase();
+            if (id === "ubuntu" || id === "debian" || idLike.includes("debian"))
+                distroFamily = "debian";
+            else if (["centos", "rhel", "fedora", "rocky", "alma", "amzn"].includes(id) || idLike.includes("rhel"))
+                distroFamily = "rhel";
+            else if (id === "arch" || idLike.includes("arch"))
+                distroFamily = "arch";
+            else if (id === "alpine")
+                distroFamily = "alpine";
+        }
+        // Detect package manager remotely
+        const pmCheck = await runRemoteCommand(environment, "command -v apt-get >/dev/null && echo apt || command -v dnf >/dev/null && echo dnf || command -v yum >/dev/null && echo yum || command -v pacman >/dev/null && echo pacman || command -v apk >/dev/null && echo apk || echo unknown");
+        const packageManager = pmCheck.trim();
+        const initCheck = await runRemoteCommand(environment, "test -d /run/systemd/system && echo systemd || test -d /etc/init.d && echo sysvinit || echo unknown");
+        const initSystem = initCheck.trim();
+        const isWSL = kernel.toLowerCase().includes("microsoft");
+        return { os: "linux", distro, distroVersion, distroFamily, kernel, isWSL, shell, packageManager, initSystem, arch };
+    }
+    catch {
+        return { os: "unknown", distro: "unknown", distroVersion: "", distroFamily: "unknown", kernel: "", isWSL: false, shell: "", packageManager: "unknown", initSystem: "unknown", arch: "" };
+    }
+}
+/**
+ * Get the correct install command for the detected platform.
+ */
+export function getInstallCommand(pkg, platform) {
+    switch (platform.packageManager) {
+        case "apt": return `sudo apt-get update && sudo apt-get install -y ${pkg}`;
+        case "dnf": return `sudo dnf install -y ${pkg}`;
+        case "yum": return `sudo yum install -y ${pkg}`;
+        case "pacman": return `sudo pacman -S --noconfirm ${pkg}`;
+        case "apk": return `sudo apk add ${pkg}`;
+        case "brew": return `brew install ${pkg}`;
+        case "choco": return `choco install ${pkg} -y`;
+        default: return `echo "Cannot determine package manager. Install ${pkg} manually."`;
+    }
+}
+/**
+ * Get the correct service management command.
+ */
+export function getServiceCommand(action, service, platform) {
+    switch (platform.initSystem) {
+        case "systemd": return `sudo systemctl ${action} ${service}`;
+        case "sysvinit": return `sudo service ${service} ${action}`;
+        case "openrc": return `sudo rc-service ${service} ${action}`;
+        case "launchd": return action === "status" ? `launchctl list | grep ${service}` : `sudo launchctl ${action === "start" ? "load" : "unload"} /Library/LaunchDaemons/${service}.plist`;
+        default: return `sudo systemctl ${action} ${service}`;
+    }
+}
+/**
+ * Map common command names to package names per distro family.
+ */
+export const COMMAND_TO_PACKAGE = {
+    whois: { debian: "whois", rhel: "whois", arch: "whois", alpine: "whois" },
+    dig: { debian: "dnsutils", rhel: "bind-utils", arch: "bind", alpine: "bind-tools" },
+    nslookup: { debian: "dnsutils", rhel: "bind-utils", arch: "bind", alpine: "bind-tools" },
+    traceroute: { debian: "traceroute", rhel: "traceroute", arch: "traceroute", alpine: "traceroute" },
+    rsync: { debian: "rsync", rhel: "rsync", arch: "rsync", alpine: "rsync" },
+    zip: { debian: "zip", rhel: "zip", arch: "zip", alpine: "zip" },
+    unzip: { debian: "unzip", rhel: "unzip", arch: "unzip", alpine: "unzip" },
+    curl: { debian: "curl", rhel: "curl", arch: "curl", alpine: "curl" },
+    wget: { debian: "wget", rhel: "wget", arch: "wget", alpine: "wget" },
+    jq: { debian: "jq", rhel: "jq", arch: "jq", alpine: "jq" },
+    htop: { debian: "htop", rhel: "htop", arch: "htop", alpine: "htop" },
+    tree: { debian: "tree", rhel: "tree", arch: "tree", alpine: "tree" },
+    locate: { debian: "mlocate", rhel: "mlocate", arch: "mlocate", alpine: "mlocate" },
+    certbot: { debian: "certbot", rhel: "certbot", arch: "certbot", alpine: "certbot" },
+    nc: { debian: "netcat-openbsd", rhel: "nmap-ncat", arch: "gnu-netcat", alpine: "netcat-openbsd" },
+};
+/**
+ * Get the package name for a command on the detected platform.
+ */
+export function getPackageForCommand(command, platform) {
+    const mapping = COMMAND_TO_PACKAGE[command];
+    if (!mapping)
+        return command; // Default: package name = command name
+    return mapping[platform.distroFamily] ?? command;
+}
+/**
+ * Format platform info for display.
+ */
+export function formatPlatform(info) {
+    const c = { reset: "\x1b[0m", bold: "\x1b[1m", dim: "\x1b[2m", cyan: "\x1b[36m", yellow: "\x1b[33m" };
+    const wslLabel = info.isWSL ? ` ${c.yellow}(WSL)${c.reset}` : "";
+    return [
+        `${c.bold}Platform:${c.reset}`,
+        `  OS:        ${info.distro}${wslLabel}`,
+        `  Kernel:    ${info.kernel}`,
+        `  Arch:      ${info.arch}`,
+        `  Shell:     ${info.shell}`,
+        `  Packages:  ${info.packageManager}`,
+        `  Init:      ${info.initSystem}`,
+    ].join("\n");
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function tryExec(cmd) {
+    try {
+        return execSync(cmd, { encoding: "utf-8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function commandExists(cmd) {
+    return tryExec(`command -v ${cmd}`) !== null;
+}
+function extractField(content, key) {
+    const match = content.match(new RegExp(`^${key}="?([^"\\n]*)"?`, "m"));
+    return match?.[1] ?? null;
+}

package/dist/utils/smartFile.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Smart file output.
+ *
+ * - Checks file size before reading
+ * - Shows a sample (head + tail) if file is large (>100 lines / >50KB)
+ * - Searches within a file for a term and shows matches with context
+ * - Detects file type and syntax-highlights key parts
+ */
+export interface FileInfo {
+    path: string;
+    exists: boolean;
+    sizeBytes: number;
+    sizeHuman: string;
+    lineCount: number;
+    isBig: boolean;
+    type: string;
+}
+/**
+ * Get file info (size, line count) before reading.
+ */
+export declare function getFileInfo(path: string, isRemote: boolean, environment?: string): Promise<FileInfo>;
+/**
+ * Read a file smartly — full content if small, sampled if large.
+ */
+export declare function smartRead(path: string, isRemote: boolean, environment?: string): Promise<string>;
+/**
+ * Search within a file for a term and show matches with context.
+ */
+export declare function smartSearch(path: string, query: string, isRemote: boolean, environment?: string, contextLines?: number): Promise<string>;

package/dist/utils/smartFile.js

@@ -0,0 +1,188 @@
+/**
+ * Smart file output.
+ *
+ * - Checks file size before reading
+ * - Shows a sample (head + tail) if file is large (>100 lines / >50KB)
+ * - Searches within a file for a term and shows matches with context
+ * - Detects file type and syntax-highlights key parts
+ */
+import { runLocalCommand } from "../execution/ssh.js";
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    cyan: "\x1b[36m",
+    magenta: "\x1b[35m",
+};
+const MAX_LINES = 80;
+const MAX_BYTES = 50 * 1024; // 50KB
+/**
+ * Get file info (size, line count) before reading.
+ */
+export async function getFileInfo(path, isRemote, environment) {
+    const run = isRemote
+        ? async (cmd) => {
+            const { runRemoteCommand } = await import("../execution/ssh.js");
+            return runRemoteCommand(environment, cmd);
+        }
+        : runLocalCommand;
+    try {
+        const info = await run(`stat -c '%s' ${path} 2>/dev/null && wc -l < ${path} 2>/dev/null && file -b ${path} 2>/dev/null`);
+        const parts = info.trim().split("\n");
+        const sizeBytes = parseInt(parts[0]) || 0;
+        const lineCount = parseInt(parts[1]) || 0;
+        const type = parts[2] ?? "unknown";
+        return {
+            path,
+            exists: true,
+            sizeBytes,
+            sizeHuman: formatBytes(sizeBytes),
+            lineCount,
+            isBig: lineCount > MAX_LINES || sizeBytes > MAX_BYTES,
+            type,
+        };
+    }
+    catch {
+        return {
+            path,
+            exists: false,
+            sizeBytes: 0,
+            sizeHuman: "0 B",
+            lineCount: 0,
+            isBig: false,
+            type: "unknown",
+        };
+    }
+}
+/**
+ * Read a file smartly — full content if small, sampled if large.
+ */
+export async function smartRead(path, isRemote, environment) {
+    const run = isRemote
+        ? async (cmd) => {
+            const { runRemoteCommand } = await import("../execution/ssh.js");
+            return runRemoteCommand(environment, cmd);
+        }
+        : runLocalCommand;
+    const info = await getFileInfo(path, isRemote, environment);
+    if (!info.exists) {
+        return `${c.red}File not found: ${path}${c.reset}`;
+    }
+    const lines = [];
+    lines.push(`${c.bold}${path}${c.reset} — ${info.sizeHuman}, ${info.lineCount} lines (${info.type})`);
+    lines.push("");
+    if (!info.isBig) {
+        // Small file — show everything
+        const content = await run(`cat ${path}`);
+        lines.push(numberLines(content.trimEnd()));
+    }
+    else {
+        // Large file — show sample
+        lines.push(`${c.yellow}⚠ Large file (${info.lineCount} lines, ${info.sizeHuman}). Showing sample.${c.reset}`);
+        lines.push("");
+        // Head
+        lines.push(`${c.cyan}── First 30 lines ──${c.reset}`);
+        const head = await run(`head -30 ${path}`);
+        lines.push(numberLines(head.trimEnd()));
+        // Tail
+        lines.push("");
+        lines.push(`${c.dim}... (${info.lineCount - 60} lines omitted) ...${c.reset}`);
+        lines.push("");
+        lines.push(`${c.cyan}── Last 30 lines ──${c.reset}`);
+        const tail = await run(`tail -30 ${path}`);
+        const tailStart = Math.max(1, info.lineCount - 29);
+        lines.push(numberLines(tail.trimEnd(), tailStart));
+        lines.push("");
+        lines.push(`${c.dim}Tip: "search <term> in ${path}" to find specific content.${c.reset}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Search within a file for a term and show matches with context.
+ */
+export async function smartSearch(path, query, isRemote, environment, contextLines = 3) {
+    const run = isRemote
+        ? async (cmd) => {
+            const { runRemoteCommand } = await import("../execution/ssh.js");
+            return runRemoteCommand(environment, cmd);
+        }
+        : runLocalCommand;
+    const info = await getFileInfo(path, isRemote, environment);
+    if (!info.exists) {
+        return `${c.red}File not found: ${path}${c.reset}`;
+    }
+    const lines = [];
+    // Run grep with context
+    const safeQuery = query.replace(/['"]/g, "");
+    try {
+        const result = await run(`grep -n -i -C ${contextLines} --color=never '${safeQuery}' ${path} 2>/dev/null | head -100`);
+        if (!result.trim()) {
+            lines.push(`${c.yellow}No matches for "${query}" in ${path}${c.reset}`);
+            return lines.join("\n");
+        }
+        // Count total matches
+        const matchCount = await run(`grep -c -i '${safeQuery}' ${path} 2>/dev/null`);
+        const count = parseInt(matchCount.trim()) || 0;
+        lines.push(`${c.bold}${path}${c.reset} — ${count} match(es) for "${c.cyan}${query}${c.reset}"`);
+        lines.push("");
+        // Format the grep output — highlight matches
+        for (const line of result.split("\n")) {
+            if (line === "--") {
+                // Grep separator between groups
+                lines.push(`${c.dim}  ---${c.reset}`);
+                continue;
+            }
+            // Line format from grep -n: "42:content" or "42-context"
+            const matchLine = line.match(/^(\d+)([:|-])(.*)$/);
+            if (matchLine) {
+                const lineNum = matchLine[1].padStart(5);
+                const isMatch = matchLine[2] === ":";
+                const content = matchLine[3];
+                if (isMatch) {
+                    // Highlight the matched term
+                    const highlighted = content.replace(new RegExp(`(${escapeRegex(safeQuery)})`, "gi"), `${c.bold}${c.red}$1${c.reset}`);
+                    lines.push(`  ${c.green}${lineNum}${c.reset} │ ${highlighted}`);
+                }
+                else {
+                    lines.push(`  ${c.dim}${lineNum}${c.reset} │ ${c.dim}${content}${c.reset}`);
+                }
+            }
+            else if (line.trim()) {
+                lines.push(`       │ ${line}`);
+            }
+        }
+        if (count > 20) {
+            lines.push("");
+            lines.push(`${c.dim}Showing first matches. Total: ${count}. Narrow your search for more specific results.${c.reset}`);
+        }
+    }
+    catch {
+        lines.push(`${c.yellow}No matches for "${query}" in ${path}${c.reset}`);
+    }
+    return lines.join("\n");
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function numberLines(content, startLine = 1) {
+    return content
+        .split("\n")
+        .map((line, i) => {
+        const num = String(startLine + i).padStart(5);
+        return `  ${c.dim}${num}${c.reset} │ ${line}`;
+    })
+        .join("\n");
+}
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1048576)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1073741824)
+        return `${(bytes / 1048576).toFixed(1)} MB`;
+    return `${(bytes / 1073741824).toFixed(1)} GB`;
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/utils/spinner.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Terminal spinner, progress bar, and animation utilities.
+ * Zero external dependencies -- uses ANSI escape codes directly.
+ * Requires Node 18+.
+ */
+export declare class Spinner {
+    private frameIndex;
+    private timer;
+    private message;
+    private stream;
+    /**
+     * Start the spinner with an initial message.
+     * If the spinner is already running it will be updated in-place.
+     */
+    start(message: string): this;
+    /** Change the message while the spinner keeps running. */
+    update(message: string): this;
+    /** Stop with a green checkmark and a final message. */
+    succeed(message?: string): void;
+    /** Stop with a red cross and a final message. */
+    fail(message?: string): void;
+    /** Stop the spinner and clear its line. */
+    stop(): void;
+    private render;
+    private clearLine;
+    private clearTimer;
+    private stopWith;
+}
+/**
+ * Convenience wrapper that starts a spinner, awaits an async function, and
+ * automatically calls `succeed` or `fail` depending on the outcome.
+ *
+ * @returns The resolved value of `fn`.
+ *
+ * ```ts
+ * const data = await withSpinner("Fetching data…", async (spinner) => {
+ *   const res = await fetch(url);
+ *   spinner.update("Parsing response…");
+ *   return res.json();
+ * });
+ * ```
+ */
+export declare function withSpinner<T>(message: string, fn: (spinner: Spinner) => Promise<T>): Promise<T>;
+/**
+ * Returns a string representing a progress bar, e.g.:
+ *
+ *     [████████░░░░░░░░░░░░] 40%
+ *
+ * @param current  Current progress value (0 … total).
+ * @param total    Value that represents 100%.
+ * @param width    Character width of the bar (default 30).
+ */
+export declare function progressBar(current: number, total: number, width?: number): string;

package/dist/utils/spinner.js

@@ -0,0 +1,140 @@
+/**
+ * Terminal spinner, progress bar, and animation utilities.
+ * Zero external dependencies -- uses ANSI escape codes directly.
+ * Requires Node 18+.
+ */
+// ---------------------------------------------------------------------------
+// ANSI helpers
+// ---------------------------------------------------------------------------
+const ESC = "\x1b[";
+const HIDE_CURSOR = `${ESC}?25l`;
+const SHOW_CURSOR = `${ESC}?25h`;
+const ERASE_LINE = `${ESC}2K`;
+const MOVE_TO_COL1 = `\r`;
+const RESET = `${ESC}0m`;
+const CYAN = `${ESC}36m`;
+const GREEN = `${ESC}32m`;
+const RED = `${ESC}31m`;
+// ---------------------------------------------------------------------------
+// Spinner
+// ---------------------------------------------------------------------------
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const INTERVAL_MS = 80;
+export class Spinner {
+    frameIndex = 0;
+    timer = null;
+    message = "";
+    stream = process.stderr;
+    /**
+     * Start the spinner with an initial message.
+     * If the spinner is already running it will be updated in-place.
+     */
+    start(message) {
+        if (this.timer) {
+            this.update(message);
+            return this;
+        }
+        this.message = message;
+        this.frameIndex = 0;
+        this.stream.write(HIDE_CURSOR);
+        this.timer = setInterval(() => {
+            this.render();
+        }, INTERVAL_MS);
+        // Render the first frame immediately so there is no 80 ms gap.
+        this.render();
+        return this;
+    }
+    /** Change the message while the spinner keeps running. */
+    update(message) {
+        this.message = message;
+        return this;
+    }
+    /** Stop with a green checkmark and a final message. */
+    succeed(message) {
+        this.stopWith(`${GREEN}✔${RESET}`, message ?? this.message);
+    }
+    /** Stop with a red cross and a final message. */
+    fail(message) {
+        this.stopWith(`${RED}✖${RESET}`, message ?? this.message);
+    }
+    /** Stop the spinner and clear its line. */
+    stop() {
+        this.clearTimer();
+        this.clearLine();
+        this.stream.write(SHOW_CURSOR);
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    render() {
+        const frame = FRAMES[this.frameIndex % FRAMES.length];
+        this.frameIndex++;
+        this.clearLine();
+        this.stream.write(`${CYAN}${frame}${RESET} ${this.message}`);
+    }
+    clearLine() {
+        this.stream.write(`${MOVE_TO_COL1}${ERASE_LINE}`);
+    }
+    clearTimer() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    stopWith(symbol, message) {
+        this.clearTimer();
+        this.clearLine();
+        this.stream.write(`${symbol} ${message}\n`);
+        this.stream.write(SHOW_CURSOR);
+    }
+}
+// ---------------------------------------------------------------------------
+// withSpinner wrapper
+// ---------------------------------------------------------------------------
+/**
+ * Convenience wrapper that starts a spinner, awaits an async function, and
+ * automatically calls `succeed` or `fail` depending on the outcome.
+ *
+ * @returns The resolved value of `fn`.
+ *
+ * ```ts
+ * const data = await withSpinner("Fetching data…", async (spinner) => {
+ *   const res = await fetch(url);
+ *   spinner.update("Parsing response…");
+ *   return res.json();
+ * });
+ * ```
+ */
+export async function withSpinner(message, fn) {
+    const spinner = new Spinner();
+    spinner.start(message);
+    try {
+        const result = await fn(spinner);
+        spinner.succeed();
+        return result;
+    }
+    catch (error) {
+        const errMsg = error instanceof Error ? error.message : String(error);
+        spinner.fail(`${message} — ${errMsg}`);
+        throw error;
+    }
+}
+// ---------------------------------------------------------------------------
+// Progress bar
+// ---------------------------------------------------------------------------
+/**
+ * Returns a string representing a progress bar, e.g.:
+ *
+ *     [████████░░░░░░░░░░░░] 40%
+ *
+ * @param current  Current progress value (0 … total).
+ * @param total    Value that represents 100%.
+ * @param width    Character width of the bar (default 30).
+ */
+export function progressBar(current, total, width = 30) {
+    const ratio = total === 0 ? 0 : Math.min(Math.max(current / total, 0), 1);
+    const filled = Math.round(ratio * width);
+    const empty = width - filled;
+    const pct = Math.round(ratio * 100);
+    return `[${GREEN}${"█".repeat(filled)}${RESET}${"░".repeat(empty)}] ${pct}%`;
+}