@aria-cli/tools 1.0.10 → 1.0.12

package/dist-cjs/executors/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @aria/tools - Shared executor utilities
+ *
+ * Common helper functions used across all executor modules.
+ */
+import type { ToolResult } from "../types.js";
+export { getErrorMessage } from "@aria-cli/types";
+/**
+ * Creates a successful result.
+ */
+export declare function success(message: string, data?: unknown): ToolResult;
+/**
+ * Creates a failure result.
+ */
+export declare function fail(message: string, data?: unknown): ToolResult;
+/**
+ * Checks if a resolved path is within the allowed base directory.
+ * Prevents path traversal attacks.
+ */
+export declare function isPathWithinBase(resolvedPath: string, baseDir: string): boolean;

package/dist-cjs/executors/utils.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * @aria/tools - Shared executor utilities
+ *
+ * Common helper functions used across all executor modules.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getErrorMessage = void 0;
+exports.success = success;
+exports.fail = fail;
+exports.isPathWithinBase = isPathWithinBase;
+const nodePath = __importStar(require("node:path"));
+var types_1 = require("@aria-cli/types");
+Object.defineProperty(exports, "getErrorMessage", { enumerable: true, get: function () { return types_1.getErrorMessage; } });
+/**
+ * Creates a successful result.
+ */
+function success(message, data) {
+    return { success: true, message, data };
+}
+/**
+ * Creates a failure result.
+ */
+function fail(message, data) {
+    return { success: false, message, data };
+}
+/**
+ * Checks if a resolved path is within the allowed base directory.
+ * Prevents path traversal attacks.
+ */
+function isPathWithinBase(resolvedPath, baseDir) {
+    const normalizedPath = nodePath.normalize(resolvedPath);
+    const normalizedBase = nodePath.normalize(baseDir);
+    // normalize() strips trailing separators except for root "/".
+    // Guard against root-as-base which would allow every absolute path.
+    const baseWithSep = normalizedBase.endsWith(nodePath.sep)
+        ? normalizedBase
+        : normalizedBase + nodePath.sep;
+    return normalizedPath === normalizedBase || normalizedPath.startsWith(baseWithSep);
+}

package/dist-cjs/executors/web.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @aria/tools - Web tool executors
+ *
+ * Implementation of web operations for ARIA tool system.
+ */
+import type { ToolContext, ToolResult } from "../types.js";
+export interface WebSearchInput {
+    /** Search query */
+    query: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Search topic classification */
+    topic?: "general" | "news";
+    /** Restrict results to these domains */
+    domains?: string[];
+    /** Exclude results from these domains */
+    excludeDomains?: string[];
+    /** Restrict results by freshness window */
+    timeRange?: "day" | "week" | "month" | "year";
+}
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    content: string;
+    score?: number;
+}
+export interface WebSearchOutput {
+    query: string;
+    results: WebSearchResult[];
+}
+/**
+ * Searches the web using the SearchProviderRouter with automatic fallback.
+ * Providers are selected based on available API keys (Brave, Tavily, Jina, Exa,
+ * Firecrawl, DuckDuckGo). DuckDuckGo is always available as a last resort.
+ *
+ * Results are cached via LRU+TTL cache for 15 minutes.
+ */
+export declare function executeWebSearch(input: WebSearchInput, ctx: ToolContext): Promise<ToolResult>;
+export interface WebFetchInput {
+    /** URL to fetch */
+    url: string;
+    /** Response format: 'text', 'html', or 'json' */
+    format?: "text" | "html" | "json";
+    /** Custom headers to include in the request */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+    /** Maximum response size in bytes (default: 1MB) */
+    maxSizeBytes?: number;
+}
+export interface WebFetchOutput {
+    content: unknown;
+    status: number;
+    contentType?: string;
+    fromCache: boolean;
+    fetchedAt: string;
+    finalUrl: string;
+    contentBytes: number;
+    truncated: boolean;
+}
+/**
+ * Fetches content from a URL with retry resilience, caching, and security wrapping.
+ * Uses fetchWithRetry for automatic retry on transient failures (429, 5xx, ECONNRESET).
+ * Results are cached via LRU+TTL cache for 15 minutes.
+ */
+export declare function executeWebFetch(input: WebFetchInput, ctx: ToolContext): Promise<ToolResult>;
+export interface BrowseInput {
+    /** URL to browse */
+    url: string;
+    /** Timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+export interface BrowseOutput {
+    url: string;
+    title: string;
+    content: string;
+    fromCache: boolean;
+    fetchedAt: string;
+    finalUrl: string;
+    contentBytes: number;
+    truncated: boolean;
+}
+/**
+ * Browses a URL by fetching its HTML content and extracting Markdown.
+ * Uses Readability.js + Turndown for article extraction with three-tier fallback.
+ * Supports GitHub URL normalization, retry on transient failures, LRU+TTL caching,
+ * and nonce-based external content wrapping.
+ */
+export declare function executeBrowse(input: BrowseInput, ctx: ToolContext): Promise<ToolResult>;