@travisennis/acai 0.0.1

package/source/tools/web-fetch.ts

@@ -0,0 +1,327 @@
+import { tool } from "ai";
+import chalk from "chalk";
+import { type CheerioAPI, load } from "cheerio";
+import { z } from "zod";
+import { logger } from "../logger.ts";
+import type { TokenCounter } from "../token-utils.ts";
+import type { SendData } from "./types.ts";
+
+export const WebFetchTool = {
+  name: "webFetch" as const,
+};
+
+export const createWebFetchTool = (options: {
+  sendData?: SendData | undefined;
+  tokenCounter: TokenCounter;
+}) => {
+  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 as 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 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 async function readUrl(
+  url: string,
+  abortSignal?: AbortSignal | undefined,
+): Promise<ReadUrlResult> {
+  let initialResponse: Response;
+  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: ContentType =
+    (initialResponse.headers.get("content-type") as ContentType) ??
+    "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 as 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: string): HtmlCleaner {
+    return new HtmlCleaner(html);
+  }
+
+  private html: string;
+
+  private constructor(html: string) {
+    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?: { simplify?: boolean; empty?: boolean }): string {
+    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
+   */
+  private removeUnnecessaryElements($: CheerioAPI): void {
+    // 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
+   */
+  private simplifyStructure($: CheerioAPI): void {
+    // 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
+   */
+  private removeEmptyElements($: CheerioAPI): void {
+    $(":empty").remove();
+  }
+}

package/source/tools/web-search.ts

@@ -0,0 +1,101 @@
+import { tool } from "ai";
+import chalk from "chalk";
+import { SafeSearchType, type SearchResult, search } from "duck-duck-scrape";
+import Exa from "exa-js";
+import { z } from "zod";
+import type { TokenCounter } from "../token-utils.ts";
+import type { SendData } from "./types.ts";
+
+export const WebSearchTool = {
+  name: "webSearch" as const,
+};
+
+export const createWebSearchTool = ({
+  sendData,
+  tokenCounter,
+}: {
+  sendData?: SendData;
+  tokenCounter: TokenCounter;
+}) => {
+  return {
+    [WebSearchTool.name]: tool({
+      description:
+        "Searches the web and returns match documents with their title, url, and text content. The query should be formulated as a natural language question.",
+      inputSchema: z.object({
+        query: z.string().describe("The search query."),
+      }),
+      execute: async ({ query }, { toolCallId }) => {
+        sendData?.({
+          id: toolCallId,
+          event: "tool-init",
+          data: `Web search: ${chalk.cyan(query)}`,
+        });
+
+        const result = await performSearch(query);
+
+        const sources = result.results.map(
+          (source) =>
+            `## ${source.title}\nURL: ${source.url}\n\n${source.text}`,
+        );
+        const resultText = `# Search Results:\n\n${sources.join("\n\n")}`;
+        const tokenCount = tokenCounter.count(resultText);
+
+        sendData?.({
+          id: toolCallId,
+          event: "tool-completion",
+          data: `Found ${result.results.length} results. (${tokenCount} tokens)`,
+        });
+
+        return resultText;
+      },
+    }),
+  };
+};
+
+async function performSearch(query: string) {
+  // Check if EXA API key is available
+  const hasExaApiKey =
+    process.env["EXA_API_KEY"] && process.env["EXA_API_KEY"].trim() !== "";
+
+  if (hasExaApiKey) {
+    // Use Exa search
+    try {
+      const exa = new Exa(process.env["EXA_API_KEY"]);
+      const result = await exa.searchAndContents(query, {
+        numResults: 5,
+        text: true,
+      });
+      return result;
+    } catch (error) {
+      // If Exa fails, fall back to duck duck scrape
+      console.info("Exa search failed, falling back to DuckDuckGo:", error);
+      return await searchWithDuckDuckGo(query);
+    }
+  } else {
+    // Use DuckDuckGo search as fallback
+    console.info("EXA_API_KEY not set, using DuckDuckGo search");
+    return await searchWithDuckDuckGo(query);
+  }
+}
+
+async function searchWithDuckDuckGo(query: string) {
+  try {
+    const searchResults = await search(query, {
+      safeSearch: SafeSearchType.MODERATE,
+    });
+
+    // Transform duck-duck-scrape results to match Exa format
+    // Take only first 5 results to match Exa behavior
+    const results = searchResults.results
+      .slice(0, 5)
+      .map((result: SearchResult) => ({
+        title: result.title,
+        url: result.url,
+        text: result.description || "",
+      }));
+
+    return { results };
+  } catch (error) {
+    throw new Error(`Failed to perform web search: ${error}`);
+  }
+}

package/source/utils/process.ts

@@ -0,0 +1,121 @@
+import { execFile } from "node:child_process";
+import { isUndefined } from "@travisennis/stdlib/typeguards";
+
+const MS_IN_SECOND = 1000;
+const SECONDS_IN_MINUTE = 60;
+const DEFAULT_TIMEOUT = 2 * SECONDS_IN_MINUTE * MS_IN_SECOND;
+
+interface ExecuteOptions {
+  /** Working directory where the command will be executed */
+  cwd?: string;
+  /** Timeout in milliseconds before killing the process */
+  timeout?: number;
+  /** AbortSignal to cancel the execution */
+  abortSignal?: AbortSignal;
+  /** Whether to use shell syntax (defaults to false) */
+  shell?: boolean;
+  /** Whether to throw an error on non-zero exit codes (defaults to false) */
+  throwOnError?: boolean;
+  /** Whether to include stdout/stderr in the result even when there's an error (defaults to true) */
+  preserveOutputOnError?: boolean;
+  /** Maximum buffer size in bytes (defaults to 1MB) */
+  maxBuffer?: number;
+}
+
+export interface ExecuteResult {
+  /** Standard output from the command */
+  stdout: string;
+  /** Standard error from the command */
+  stderr: string;
+  /** Exit code (0 for success, non-zero for errors) */
+  code: number;
+  /** The signal that terminated the process, if any */
+  signal?: NodeJS.Signals;
+}
+
+/**
+ * Executes a command and returns the result, providing unified error handling
+ *
+ * @param command Either a string command with arguments or an array where the first item is the command
+ *               and the rest are arguments
+ * @param options Execution options
+ * @returns Promise resolving to an object containing stdout, stderr, and exit code
+ */
+export function executeCommand(
+  command: string | [string, ...string[]],
+  options?: ExecuteOptions,
+): Promise<ExecuteResult> {
+  const {
+    cwd = process.cwd(),
+    timeout = DEFAULT_TIMEOUT,
+    abortSignal,
+    shell = false,
+    throwOnError = false,
+    preserveOutputOnError = true,
+    maxBuffer = 1_000_000,
+  } = options || {};
+
+  let cmd: string;
+  let args: string[];
+
+  if (Array.isArray(command)) {
+    [cmd, ...args] = command;
+  } else {
+    const parts = command.split(" ");
+    cmd = parts[0] ?? "";
+    args = parts.slice(1);
+  }
+
+  if (isUndefined(cmd) || cmd.trim() === "") {
+    const result: ExecuteResult = {
+      stdout: "",
+      stderr: "Missing command",
+      code: 1,
+    };
+    return throwOnError
+      ? Promise.reject(new Error("Missing command"))
+      : Promise.resolve(result);
+  }
+
+  return new Promise<ExecuteResult>((resolve, reject) => {
+    try {
+      execFile(
+        cmd,
+        args,
+        {
+          cwd,
+          timeout,
+          signal: abortSignal,
+          shell,
+          maxBuffer,
+        },
+        (error, stdout, stderr) => {
+          if (error) {
+            const errorCode = typeof error.code === "number" ? error.code : 1;
+            const result: ExecuteResult = {
+              stdout: preserveOutputOnError ? stdout : "",
+              stderr: preserveOutputOnError ? stderr : "",
+              code: errorCode,
+              signal: error.signal ?? undefined,
+            };
+
+            if (throwOnError) {
+              reject(Object.assign(error, { result }));
+            } else {
+              resolve(result);
+            }
+          } else {
+            resolve({ stdout, stderr, code: 0 });
+          }
+        },
+      );
+    } catch (error) {
+      const result: ExecuteResult = { stdout: "", stderr: "", code: 1 };
+      if (throwOnError) {
+        reject(error);
+      } else {
+        resolve(result);
+      }
+    }
+  });
+}

package/source/version.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from "node:fs";
+import { join } from "@travisennis/stdlib/desm";
+
+export function getPackageVersion(fallback = "unavailable"): string {
+  try {
+    const pkgPath = join(import.meta.url, "..", "package.json");
+    const pkgRaw = readFileSync(pkgPath, "utf8");
+    const parsed = JSON.parse(pkgRaw) as { version?: unknown };
+    const v = typeof parsed.version === "string" ? parsed.version : undefined;
+    if (v && v.length > 0) {
+      return v;
+    }
+  } catch {
+    // ignore
+  }
+  const envV = process.env["npm_package_version"];
+  if (typeof envV === "string" && envV.length > 0) {
+    return envV;
+  }
+  return fallback;
+}

package/test/commands/copy-command.test.ts

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { ModelMessage, TextPart } from "ai";
+import { copyCommand } from "../../source/commands/copy-command.ts";
+import type { CommandOptions } from "../../source/commands/types.ts";
+
+function makeAssistant(text: string): ModelMessage {
+  return {
+    role: "assistant",
+    content: [{ type: "text", text } as TextPart],
+  } as ModelMessage;
+}
+
+function makeUser(text: string): ModelMessage {
+  return {
+    role: "user",
+    content: [{ type: "text", text } as TextPart],
+  } as ModelMessage;
+}
+
+describe("/copy command", () => {
+  it("returns info when no assistant response exists", async () => {
+    const outputs: string[] = [];
+    const options = {
+      terminal: {
+        info: (msg: string) => outputs.push(`info:${msg}`),
+        success: (_msg: string) => outputs.push("success"),
+        error: (_msg: string) => outputs.push("error"),
+      },
+      messageHistory: {
+        get: () => [makeUser("hello")] as ModelMessage[],
+      },
+    } as unknown as CommandOptions;
+
+    const cmd = copyCommand(options);
+    await cmd.execute([]);
+
+    assert(outputs.some((o) => o.startsWith("info:")));
+  });
+
+  it("copies last assistant text via clipboard and reports success", async (_t) => {
+    // Temporarily replace writeToClipboard by monkey-patching module function via dynamic import cache
+    const outputs: string[] = [];
+    const options = {
+      terminal: {
+        info: (msg: string) => outputs.push(`info:${msg}`),
+        success: (msg: string) => outputs.push(`success:${msg}`),
+        error: (msg: string) => outputs.push(`error:${msg}`),
+      },
+      messageHistory: {
+        get: () =>
+          [makeUser("hello"), makeAssistant("world")] as ModelMessage[],
+      },
+    } as unknown as CommandOptions;
+
+    // We cannot easily mock child_process spawn without a mocking framework; this test focuses on flow.
+    // Execute should attempt clipboard; since environment may not have tools, we only assert it didn't crash synchronously.
+    const cmd = copyCommand(options);
+
+    try {
+      await cmd.execute([]);
+    } catch {
+      // Ignore runtime env clipboard errors
+    }
+
+    // Should either success or error, but not be silent
+    assert(outputs.length > 0);
+  });
+});