@travisennis/acai 0.0.1

package/dist/tools/read-file.js

@@ -0,0 +1,86 @@
+import fs from "node:fs/promises";
+import { isNumber } from "@travisennis/stdlib/typeguards";
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import { config } from "../config.js";
+import { joinWorkingDir, validatePath } from "./filesystem-utils.js";
+import { fileEncodingSchema } from "./types.js";
+export const ReadFileTool = {
+    name: "readFile",
+};
+export const createReadFileTool = async ({ workingDir, sendData, tokenCounter, }) => {
+    const allowedDirectory = workingDir;
+    return {
+        [ReadFileTool.name]: tool({
+            description: "Read the complete contents of a file from the file system unless startLine and lineCount are given to read a file selection. " +
+                "Handles various text encodings and provides detailed error messages " +
+                "if the file cannot be read. Use this tool when you need to examine " +
+                "the contents of a single file. Only works within allowed directories.",
+            inputSchema: z.object({
+                path: z.string().describe("Absolute path to file to read"),
+                encoding: fileEncodingSchema.describe('Encoding format for reading the file. Use "utf-8" as default for text files'),
+                startLine: z
+                    .number()
+                    .nullable()
+                    .describe("1-based line number to start reading from. Pass null to start at beginning of file"),
+                lineCount: z
+                    .number()
+                    .nullable()
+                    .describe("Maximum number of lines to read. Pass null to get all lines."),
+            }),
+            execute: async ({ path: providedPath, encoding, startLine, lineCount, }, { toolCallId }) => {
+                sendData?.({
+                    id: toolCallId,
+                    event: "tool-init",
+                    data: `Reading file: ${chalk.cyan(providedPath)}${startLine ? chalk.cyan(`:${startLine}`) : ""}${lineCount ? chalk.cyan(`:${lineCount}`) : ""}`,
+                });
+                try {
+                    const filePath = await validatePath(joinWorkingDir(providedPath, workingDir), allowedDirectory);
+                    let file = await fs.readFile(filePath, { encoding });
+                    // Apply line-based selection if requested
+                    if (isNumber(startLine) || isNumber(lineCount)) {
+                        const lines = file.split("\n");
+                        const totalLines = lines.length;
+                        const startIndex = (startLine ?? 1) - 1; // Default to start of file if only lineCount is given
+                        const count = lineCount ?? totalLines - startIndex; // Default to read all lines from start if only startLine is given
+                        if (startIndex < 0 || startIndex >= totalLines) {
+                            return `startLine ${startLine} is out of bounds for file with ${totalLines} lines.`;
+                        }
+                        const endIndex = Math.min(startIndex + count, totalLines);
+                        file = lines.slice(startIndex, endIndex).join("\n");
+                    }
+                    let tokenCount = 0;
+                    try {
+                        // Only calculate tokens for non-image files and if encoding is text-based
+                        if (encoding.startsWith("utf")) {
+                            tokenCount = tokenCounter.count(file);
+                        }
+                    }
+                    catch (tokenError) {
+                        console.error("Error calculating token count:", tokenError);
+                        // Log or handle error, but don't block file return
+                    }
+                    const maxTokens = (await config.readProjectConfig()).tools.maxTokens;
+                    // Adjust max token check message if line selection was used
+                    const maxTokenMessage = isNumber(startLine) || isNumber(lineCount)
+                        ? `Selected file content (${tokenCount} tokens) exceeds maximum allowed tokens (${maxTokens}). Consider adjusting startLine/lineCount or using grepFiles.`
+                        : `File content (${tokenCount} tokens) exceeds maximum allowed tokens (${maxTokens}). Please use startLine and lineCount parameters to read specific portions of the file, or using grepFiles to search for specific content.`;
+                    const result = tokenCount <= maxTokens ? file : maxTokenMessage;
+                    sendData?.({
+                        id: toolCallId,
+                        event: "tool-completion",
+                        // Include token count only if calculated (i.e., for text files)
+                        data: tokenCount <= maxTokens
+                            ? `File read successfully ${tokenCount > 0 ? ` (${tokenCount} tokens)` : ""}`
+                            : result,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    return `Failed to read file: ${error.message}`;
+                }
+            },
+        }),
+    };
+};

package/dist/tools/read-multiple-files.d.ts

@@ -0,0 +1,14 @@
+import type { TokenCounter } from "../token-utils.ts";
+import type { SendData } from "./types.ts";
+export declare const ReadMultipleFilesTool: {
+    name: "readMultipleFiles";
+};
+export declare const createReadMultipleFilesTool: ({ workingDir, sendData, tokenCounter, }: {
+    workingDir: string;
+    sendData?: SendData;
+    tokenCounter: TokenCounter;
+}) => Promise<{
+    readMultipleFiles: import("ai").Tool<{
+        paths: string[];
+    }, string>;
+}>;

package/dist/tools/read-multiple-files.js

@@ -0,0 +1,55 @@
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import { config } from "../config.js";
+import { readFileAndCountTokens } from "./filesystem-utils.js";
+export const ReadMultipleFilesTool = {
+    name: "readMultipleFiles",
+};
+export const createReadMultipleFilesTool = async ({ workingDir, sendData, tokenCounter, }) => {
+    const allowedDirectory = workingDir;
+    return {
+        [ReadMultipleFilesTool.name]: tool({
+            description: "Read the contents of multiple files simultaneously. This is more " +
+                "efficient than reading files one by one when you need to analyze " +
+                "or compare multiple files. Each file's content is returned with its " +
+                "path as a reference. Failed reads for individual files won't stop " +
+                "the entire operation. Only works within allowed directories.",
+            inputSchema: z.object({
+                paths: z.array(z.string()),
+            }),
+            execute: async ({ paths }, { toolCallId }) => {
+                sendData?.({
+                    id: toolCallId,
+                    event: "tool-init",
+                    data: `Reading files: ${paths.map((p) => chalk.cyan(p)).join(", ")}`,
+                });
+                const maxTokens = (await config.readProjectConfig()).tools.maxTokens;
+                const results = await Promise.all(paths.map((filePath) => readFileAndCountTokens(filePath, workingDir, allowedDirectory, tokenCounter, maxTokens)));
+                let totalTokens = 0;
+                let filesReadCount = 0;
+                const formattedResults = results.map((result) => {
+                    if (result.error) {
+                        return `${result.path}: Error - ${result.error}`;
+                    }
+                    // Check if tokenCount is > 0, meaning it wasn't skipped
+                    if (result.tokenCount > 0) {
+                        filesReadCount++;
+                    }
+                    totalTokens += result.tokenCount; // Add the token count (will be 0 for skipped files)
+                    // Return content (or max token message)
+                    return `${result.path}:\n${result.content}\n`;
+                });
+                const completionMessage = filesReadCount === paths.length
+                    ? `Read ${paths.length} files successfully (${totalTokens} total tokens).`
+                    : `Read ${filesReadCount} of ${paths.length} files successfully (${totalTokens} total tokens). Files exceeding token limit were skipped.`;
+                sendData?.({
+                    id: toolCallId,
+                    event: "tool-completion",
+                    data: completionMessage,
+                });
+                return formattedResults.join("\n---\n");
+            },
+        }),
+    };
+};

package/dist/tools/save-file.d.ts

@@ -0,0 +1,17 @@
+import type { Terminal } from "../terminal/index.ts";
+import { type SendData } from "./types.ts";
+export declare const SaveFileTool: {
+    name: "saveFile";
+};
+export declare const createSaveFileTool: ({ workingDir, sendData, terminal, autoAcceptAll, }: {
+    workingDir: string;
+    sendData?: SendData;
+    terminal?: Terminal;
+    autoAcceptAll?: boolean;
+}) => Promise<{
+    saveFile: import("ai").Tool<{
+        path: string;
+        content: string;
+        encoding: "utf8" | "ascii" | "utf-8" | "utf16le" | "ucs2" | "ucs-2" | "base64" | "base64url" | "latin1" | "binary" | "hex";
+    }, string>;
+}>;

package/dist/tools/save-file.js

@@ -0,0 +1,98 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { input, select } from "@inquirer/prompts";
+import { tool } from "ai";
+import chalk from "chalk";
+import { z } from "zod";
+import { joinWorkingDir, validatePath } from "./filesystem-utils.js";
+import { fileEncodingSchema } from "./types.js";
+export const SaveFileTool = {
+    name: "saveFile",
+};
+export const createSaveFileTool = async ({ workingDir, sendData, terminal, autoAcceptAll, }) => {
+    const allowedDirectory = workingDir;
+    let autoAcceptSaves = autoAcceptAll ?? false;
+    return {
+        [SaveFileTool.name]: tool({
+            description: "Create a new file or completely overwrite an existing file with new content. " +
+                "Use with caution as it will overwrite existing files without warning. " +
+                "Handles text content with proper encoding. Only works within allowed directories.",
+            inputSchema: z.object({
+                path: z.string().describe("Absolute path to file to save to"),
+                content: z.string().describe("Content to save in the file"),
+                encoding: fileEncodingSchema.describe('Encoding format for saving the file. Use "utf-8" as default for text files'),
+            }),
+            execute: async ({ path: userPath, content, encoding, }, { toolCallId }) => {
+                sendData?.({
+                    id: toolCallId,
+                    event: "tool-init",
+                    data: `Saving file: ${chalk.cyan(userPath)}`,
+                });
+                try {
+                    const filePath = await validatePath(joinWorkingDir(userPath, workingDir), allowedDirectory);
+                    if (terminal) {
+                        terminal.writeln(`\n${chalk.blue.bold("●")} Proposing file save: ${chalk.cyan(userPath)}`);
+                        terminal.lineBreak();
+                        terminal.writeln("Proposed file content:");
+                        terminal.lineBreak();
+                        terminal.display(content);
+                        terminal.lineBreak();
+                        let userChoice;
+                        if (autoAcceptSaves) {
+                            terminal.writeln(chalk.green("✓ Auto-accepting saves (all future saves will be accepted)"));
+                            userChoice = "accept";
+                        }
+                        else {
+                            userChoice = await select({
+                                message: "What would you like to do with this file?",
+                                choices: [
+                                    { name: "Accept and save this file", value: "accept" },
+                                    {
+                                        name: "Accept all future saves (including this)",
+                                        value: "accept-all",
+                                    },
+                                    { name: "Reject this save", value: "reject" },
+                                ],
+                                default: "accept",
+                            });
+                        }
+                        terminal.lineBreak();
+                        if (userChoice === "accept-all") {
+                            autoAcceptSaves = true;
+                            terminal.writeln(chalk.yellow("✓ Auto-accept mode enabled for all future saves"));
+                            terminal.lineBreak();
+                        }
+                        if (userChoice === "reject") {
+                            const reason = await input({ message: "Feedback: " });
+                            terminal.lineBreak();
+                            sendData?.({
+                                id: toolCallId,
+                                event: "tool-completion",
+                                data: `Save rejected by user. Reason: ${reason}`,
+                            });
+                            return `The user rejected this save. Reason: ${reason}`;
+                        }
+                        // If accepted, proceed to write file
+                    }
+                    // Ensure parent directory exists
+                    await fs.mkdir(path.dirname(filePath), { recursive: true });
+                    await fs.writeFile(filePath, content, { encoding });
+                    sendData?.({
+                        id: toolCallId,
+                        event: "tool-completion",
+                        data: `File saved successfully: ${userPath}`,
+                    });
+                    return `File saved successfully: ${filePath}`;
+                }
+                catch (error) {
+                    sendData?.({
+                        id: toolCallId,
+                        event: "tool-error",
+                        data: `Failed to save file: ${error.message}`,
+                    });
+                    return `Failed to save file: ${error.message}`;
+                }
+            },
+        }),
+    };
+};

package/dist/tools/think.d.ts

@@ -0,0 +1,11 @@
+import type { SendData } from "./types.ts";
+export declare const ThinkTool: {
+    name: "think";
+};
+export declare const createThinkTool: (options?: {
+    sendData?: SendData | undefined;
+}) => {
+    think: import("ai").Tool<{
+        thought: string;
+    }, string>;
+};

package/dist/tools/think.js

@@ -0,0 +1,45 @@
+import { tool } from "ai";
+import { z } from "zod";
+export const ThinkTool = {
+    name: "think",
+};
+const toolDescription = `Use the tool to think about something. It will not obtain new information or make any changes to the repository, but just log the thought. Use it when complex reasoning or brainstorming is needed.
+Common use cases:
+1. When exploring a repository and discovering the source of a bug, call this tool to brainstorm several unique ways of fixing the bug, and assess which change(s) are likely to be simplest and most effective
+2. After receiving test results, use this tool to brainstorm ways to fix failing tests
+3. When planning a complex refactoring, use this tool to outline different approaches and their tradeoffs
+4. When designing a new feature, use this tool to think through architecture decisions and implementation details
+5. When debugging a complex issue, use this tool to organize your thoughts and hypotheses
+The tool simply logs your thought process for better transparency and does not execute any code or make changes.`;
+// This is a no-op tool that logs a thought. It is inspired by the tau-bench think tool.
+export const createThinkTool = (options = {}) => {
+    const { sendData } = options;
+    return {
+        [ThinkTool.name]: tool({
+            description: toolDescription,
+            inputSchema: z.object({
+                thought: z.string().describe("Your thought"),
+            }),
+            execute: ({ thought }, { toolCallId }) => {
+                // Replace literal '\\n' with actual newline characters
+                const formattedThought = thought.replace(/\\n/g, "\n");
+                sendData?.({
+                    event: "tool-init",
+                    id: toolCallId,
+                    data: "Logging Thought",
+                });
+                sendData?.({
+                    event: "tool-update",
+                    id: toolCallId,
+                    data: { primary: "Thought:", secondary: [formattedThought] },
+                });
+                sendData?.({
+                    event: "tool-completion",
+                    id: toolCallId,
+                    data: "Done",
+                });
+                return Promise.resolve("Your thought has been logged.");
+            },
+        }),
+    };
+};

package/dist/tools/types.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export declare const fileEncodingSchema: z.ZodEnum<["ascii", "utf8", "utf-8", "utf16le", "ucs2", "ucs-2", "base64", "base64url", "latin1", "binary", "hex"]>;
+interface MessageData {
+    primary: string;
+    secondary?: string[] | undefined;
+}
+interface BaseMessage {
+    id: string;
+    retry?: number;
+}
+interface ToolInitMessage extends BaseMessage {
+    event: "tool-init";
+    data: string;
+}
+interface ToolErrorMessage extends BaseMessage {
+    event: "tool-error";
+    data: string;
+}
+interface ToolCompletionMessage extends BaseMessage {
+    event: "tool-completion";
+    data: string;
+}
+interface ToolUpdateMessage extends BaseMessage {
+    event: "tool-update";
+    data: MessageData;
+}
+export type Message = ToolInitMessage | ToolErrorMessage | ToolCompletionMessage | ToolUpdateMessage;
+export type SendData = ({ data, event, id, retry, }: Message) => void | Promise<void>;
+export {};

package/dist/tools/types.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const fileEncodingSchema = z.enum([
+    "ascii",
+    "utf8",
+    "utf-8",
+    "utf16le",
+    "ucs2",
+    "ucs-2",
+    "base64",
+    "base64url",
+    "latin1",
+    "binary",
+    "hex",
+]);

package/dist/tools/web-fetch.d.ts

@@ -0,0 +1,47 @@
+import type { TokenCounter } from "../token-utils.ts";
+import type { SendData } from "./types.ts";
+export declare const WebFetchTool: {
+    name: "webFetch";
+};
+export declare const createWebFetchTool: (options: {
+    sendData?: SendData | undefined;
+    tokenCounter: TokenCounter;
+}) => {
+    webFetch: import("ai").Tool<{
+        url: string;
+    }, string>;
+};
+export type ContentType = "text/plain" | "text/html" | "text/markdown" | "application/json" | "application/xml" | "application/pdf" | "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/svg+xml" | "audio/mpeg" | "audio/wav" | "video/mp4" | "video/webm" | "application/zip" | "application/octet-stream";
+export type ReadUrlResult = {
+    contentType: ContentType;
+    data: string;
+};
+export declare function readUrl(url: string, abortSignal?: AbortSignal | undefined): Promise<ReadUrlResult>;
+export declare class HtmlCleaner {
+    static new(html: string): HtmlCleaner;
+    private html;
+    private constructor();
+    /**
+     * Cleans HTML content by removing unnecessary elements and simplifying structure
+     * @param {Object} [options] - Configuration options for cleaning
+     * @param {boolean} [options.simplify=true] - Whether to simplify HTML structure by removing redundant elements
+     * @param {boolean} [options.empty=true] - Whether to remove empty elements from the HTML
+     * @returns {string} Cleaned HTML content with removed whitespace and line breaks
+     */
+    clean(options?: {
+        simplify?: boolean;
+        empty?: boolean;
+    }): string;
+    /**
+     * Removes scripts, styles, and comments from HTML
+     */
+    private removeUnnecessaryElements;
+    /**
+     * Simplifies HTML structure by merging redundant tags
+     */
+    private simplifyStructure;
+    /**
+     * Removes empty elements from HTML
+     */
+    private removeEmptyElements;
+}

package/dist/tools/web-fetch.js

@@ -0,0 +1,246 @@
+import { tool } from "ai";
+import chalk from "chalk";
+import { load } from "cheerio";
+import { z } from "zod";
+import { logger } from "../logger.js";
+export const WebFetchTool = {
+    name: "webFetch",
+};
+export const createWebFetchTool = (options) => {
+    const { sendData } = options;
+    return {
+        [WebFetchTool.name]: tool({
+            description: "Fetches the content of a given URL. It intelligently handles HTML content by attempting to use a specialized service for cleaner extraction, falling back to local cleaning if needed. For non-HTML content (like plain text or markdown), it fetches the raw content directly. IMPORTANT: Does not retrieve binary files.",
+            inputSchema: z.object({
+                url: z.string().describe("The URL to fetch content from."),
+            }),
+            execute: async ({ url }, { toolCallId, abortSignal }) => {
+                try {
+                    sendData?.({
+                        event: "tool-init",
+                        id: toolCallId,
+                        data: `Reading URL: ${chalk.cyan(url)}`,
+                    });
+                    logger.info(`Initiating fetch for URL: ${url}`);
+                    const result = await readUrl(url, abortSignal);
+                    const urlContent = result.data;
+                    const tokenCount = options.tokenCounter.count(urlContent);
+                    sendData?.({
+                        event: "tool-completion",
+                        id: toolCallId,
+                        data: `Read URL successfully (${tokenCount} tokens)`,
+                    });
+                    logger.info(`Successfully read URL: ${url} (${tokenCount} tokens)`);
+                    return urlContent;
+                }
+                catch (error) {
+                    const errorMessage = error.message;
+                    sendData?.({
+                        event: "tool-error",
+                        id: toolCallId,
+                        data: `Error reading URL ${url}: ${errorMessage}`,
+                    });
+                    logger.error(`Error reading URL ${url}: ${errorMessage}`);
+                    // Return the error message so the LLM knows the tool failed.
+                    return `Failed to read URL: ${errorMessage}`;
+                }
+            },
+        }),
+    };
+};
+export async function readUrl(url, abortSignal) {
+    let initialResponse;
+    try {
+        // Initial fetch to check content type and potentially use directly
+        logger.debug(`Performing initial fetch for: ${url}`);
+        initialResponse = await fetch(url, { signal: abortSignal });
+        if (!initialResponse.ok) {
+            throw new Error(`HTTP error! status: ${initialResponse.status} ${initialResponse.statusText}`);
+        }
+        logger.debug(`Initial fetch successful for: ${url}, Status: ${initialResponse.status}`);
+    }
+    catch (error) {
+        // If the initial fetch fails entirely, rethrow
+        logger.error(`Initial fetch failed for ${url}: ${error}`);
+        throw new Error(`Error fetching initial data for ${url}: ${error}`);
+    }
+    const contentType = initialResponse.headers.get("content-type") ??
+        "text/plain";
+    logger.debug(`Content-Type for ${url}: ${contentType}`);
+    // If content type is HTML, try Jina first
+    if (contentType.includes("text/html")) {
+        logger.info(`Detected HTML content for ${url}. Attempting Jina AI fetch.`);
+        try {
+            const apiKey = process.env["JINA_READER_API_KEY"];
+            if (!apiKey) {
+                logger.warn("JINA_READER_API_KEY not set. Skipping Jina fetch.");
+                throw new Error("Jina API key not available"); // Skip to fallback
+            }
+            const jinaReadUrl = `https://r.jina.ai/${url}`;
+            logger.debug(`Fetching with Jina: ${jinaReadUrl}`);
+            const jinaResponse = await fetch(jinaReadUrl, {
+                method: "GET",
+                headers: {
+                    // biome-ignore lint/style/useNamingConvention: API requirement
+                    Authorization: `Bearer ${apiKey}`,
+                    "X-With-Generated-Alt": "true", // Optional: Ask Jina to include image descriptions
+                    "X-With-Links-Summary": "true", // Optional: Ask Jina for a summary of links
+                },
+                signal: abortSignal,
+            });
+            if (jinaResponse.ok) {
+                const data = await jinaResponse.text();
+                logger.info(`Successfully fetched and processed HTML URL with Jina: ${url}`);
+                return {
+                    contentType,
+                    data,
+                };
+            }
+            logger.warn(`Jina fetch failed for ${url} with status ${jinaResponse.status}: ${jinaResponse.statusText}. Falling back to direct fetch and clean.`);
+            // Fall through to use the initialResponse if Jina fails
+        }
+        catch (error) {
+            logger.warn(`Error fetching from Jina for ${url}: ${error.message}. Falling back to direct fetch and clean.`);
+            // Fall through to use the initialResponse if Jina fails
+        }
+        // Fallback for HTML: Use the initial response and clean it
+        try {
+            logger.warn(`Falling back to direct fetch and cleaning for HTML URL: ${url}`);
+            const htmlText = await initialResponse.text();
+            logger.debug(`Cleaning HTML content for ${url} (length: ${htmlText.length})`);
+            const cleaner = HtmlCleaner.new(htmlText);
+            const processedText = cleaner.clean();
+            logger.info(`Successfully cleaned HTML content for ${url} (length: ${processedText.length})`);
+            return {
+                contentType,
+                data: processedText,
+            };
+        }
+        catch (cleanError) {
+            logger.error(`Error cleaning HTML from fallback fetch for ${url}: ${cleanError}`);
+            throw new Error(`Error cleaning HTML from fallback fetch for ${url}: ${cleanError}`);
+        }
+    }
+    else {
+        // If not HTML, return the text directly from the initial response
+        logger.info(`Fetched non-HTML content directly: ${url} (Content-Type: ${contentType})`);
+        try {
+            if (contentType.startsWith("image/")) {
+                const arrayBuffer = await initialResponse.arrayBuffer();
+                const base64 = Buffer.from(arrayBuffer).toString("base64");
+                const base64Url = `data:${contentType};base64,${base64}`;
+                logger.debug(`Returning base64 image data for ${url} (length: ${base64.length})`);
+                return {
+                    contentType,
+                    data: base64Url,
+                };
+            }
+            const textContent = await initialResponse.text();
+            logger.debug(`Returning raw text content for ${url} (length: ${textContent.length})`);
+            return {
+                contentType,
+                data: textContent,
+            };
+        }
+        catch (textError) {
+            logger.error(`Error reading response for ${url}: ${textError}`);
+            throw new Error(`Error reading response for ${url}: ${textError}`);
+        }
+    }
+}
+export class HtmlCleaner {
+    static new(html) {
+        return new HtmlCleaner(html);
+    }
+    html;
+    constructor(html) {
+        this.html = html;
+    }
+    /**
+     * Cleans HTML content by removing unnecessary elements and simplifying structure
+     * @param {Object} [options] - Configuration options for cleaning
+     * @param {boolean} [options.simplify=true] - Whether to simplify HTML structure by removing redundant elements
+     * @param {boolean} [options.empty=true] - Whether to remove empty elements from the HTML
+     * @returns {string} Cleaned HTML content with removed whitespace and line breaks
+     */
+    clean(options) {
+        const { simplify = true, empty = true } = options ?? {};
+        const $ = load(this.html);
+        // Remove scripts, styles, and comments
+        this.removeUnnecessaryElements($);
+        // Simplify HTML structure
+        if (simplify) {
+            this.simplifyStructure($);
+        }
+        // Remove empty elements
+        if (empty) {
+            this.removeEmptyElements($);
+        }
+        // Get cleaned HTML
+        return $.html()
+            .trim()
+            .replace(/^\s*[\r\n]/gm, "");
+    }
+    /**
+     * Removes scripts, styles, and comments from HTML
+     */
+    removeUnnecessaryElements($) {
+        // Remove all script tags
+        $("script").remove();
+        // Remove all noscript tags
+        $("noscript").remove();
+        // Remove all style tags
+        $("style").remove();
+        // Remove all link tags (external stylesheets)
+        $('link[rel="stylesheet"]').remove();
+        // Remove all preload link tags
+        $('link[rel="preload"]').remove();
+        // Remove all link tags
+        $("link").remove();
+        // Remove all forms
+        $("form").remove();
+        // Remove comments
+        $("*")
+            .contents()
+            .each((_, element) => {
+            if (element.type === "comment") {
+                $(element).remove();
+            }
+        });
+        // Remove all inline styles
+        $("[style]").removeAttr("style");
+        // Remove all class attributes
+        $("[class]").removeAttr("class");
+        // Remove all id attributes
+        $("[id]").removeAttr("id");
+    }
+    /**
+     * Simplifies HTML structure by merging redundant tags
+     */
+    simplifyStructure($) {
+        // Merge nested divs
+        $("div div").each((_, element) => {
+            const $element = $(element);
+            const parent = $element.parent();
+            if (parent.children().length === 1 && parent.get(0)?.tagName === "div") {
+                $element.unwrap();
+            }
+        });
+        // Remove redundant spans
+        $("span").each((_, element) => {
+            const $element = $(element);
+            if (!$element.attr() || Object.keys($element.attr() ?? {}).length === 0) {
+                const h = $element.html();
+                if (h) {
+                    $element.replaceWith(h);
+                }
+            }
+        });
+    }
+    /**
+     * Removes empty elements from HTML
+     */
+    removeEmptyElements($) {
+        $(":empty").remove();
+    }
+}