@aria-cli/tools 1.0.10 → 1.0.12

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

@@ -0,0 +1,150 @@
+/**
+ * @aria/tools - Filesystem tool executors
+ *
+ * Implementation of filesystem operations for ARIA tool system.
+ */
+import type { ToolContext, ToolResult } from "../types.js";
+/**
+ * Hard output caps to avoid overwhelming tool responses.
+ * read_file already has media-size capping and line slicing support.
+ */
+export declare const FILESYSTEM_OUTPUT_LIMITS: {
+    readonly MAX_GLOB_RESULTS: 2000;
+    readonly MAX_GREP_MATCHES: 2000;
+    readonly MAX_GREP_ERRORS: 200;
+    readonly MAX_GREP_FILE_BYTES: number;
+    readonly MAX_GREP_LINE_BYTES: number;
+};
+export interface ReadFileInput {
+    path: string;
+    /** File encoding */
+    encoding?: string;
+    /** Line offset (0-based) to start reading from */
+    offset?: number;
+    /** Number of lines to read */
+    limit?: number;
+}
+/**
+ * Reads a file's contents.
+ */
+export declare function executeReadFile(input: ReadFileInput, ctx: ToolContext): Promise<ToolResult>;
+export interface WriteFileInput {
+    path: string;
+    content: string;
+    /** File encoding */
+    encoding?: string;
+    /** Append to file instead of overwriting */
+    append?: boolean;
+    /**
+     * Optional optimistic concurrency guard.
+     * If provided, write only succeeds when current file content hash matches this value.
+     */
+    expectedHash?: string;
+}
+/**
+ * Writes content to a file.
+ */
+export declare function executeWriteFile(input: WriteFileInput, ctx: ToolContext): Promise<ToolResult>;
+export interface EditFileInput {
+    path: string;
+    oldText: string;
+    newText: string;
+    /** Replace all occurrences instead of just the first */
+    replaceAll?: boolean;
+    /**
+     * Optional replacement count assertion.
+     * When provided, the edit fails unless this exact number of replacements is applied.
+     */
+    expectedReplacements?: number;
+    /**
+     * Optional optimistic concurrency guard.
+     * If provided, edit only succeeds when current file content hash matches this value.
+     */
+    expectedHash?: string;
+}
+/**
+ * Edits a file by replacing text.
+ */
+export declare function executeEditFile(input: EditFileInput, ctx: ToolContext): Promise<ToolResult>;
+export interface ListDirInput {
+    path?: string;
+    /** Include dotfiles and dot-directories */
+    all?: boolean;
+    /** Include detailed metadata fields */
+    long?: boolean;
+    /** Recursion depth: 1 lists immediate children, 2 includes grandchildren, etc. */
+    depth?: number;
+    /** Maximum number of entries to return */
+    limit?: number;
+    /** Number of entries to skip before returning */
+    offset?: number;
+    /** Glob patterns to ignore */
+    ignore?: string[];
+}
+/** Backward-compatible ls input alias. */
+export interface LsInput extends ListDirInput {
+}
+export interface LsEntry {
+    name: string;
+    type: "file" | "directory" | "symlink" | "other";
+    /** File size in bytes (present when long=true) */
+    size?: number;
+    /** POSIX mode bits as a zero-padded octal string, e.g. "644" */
+    mode?: string;
+    /** Last modified time in epoch milliseconds (integer, present when long=true) */
+    mtimeMs?: number;
+    /** Last modified time as ISO-8601 string (present when long=true) */
+    modifiedAt?: string;
+}
+export interface ListDirEntry extends LsEntry {
+    /** Relative path from listing root */
+    path: string;
+    /** Depth from listing root where 1 is an immediate child */
+    depth: number;
+}
+export interface ListDirOutput {
+    path: string;
+    depth: number;
+    limit: number;
+    offset: number;
+    ignore: string[];
+    truncated: boolean;
+    total: number;
+    entries: ListDirEntry[];
+}
+export declare const LS_INTERNALS: {
+    readType(entryPath: string): Promise<LsEntry["type"]>;
+    readMetadata(entryPath: string): Promise<Required<Pick<LsEntry, "size" | "mode" | "mtimeMs" | "modifiedAt">>>;
+};
+/**
+ * List files and directories with structured metadata.
+ */
+export declare function executeLs(input: ListDirInput, ctx: ToolContext): Promise<ToolResult>;
+export interface GlobInput {
+    pattern: string;
+    /** Working directory for the glob */
+    cwd?: string;
+    /** Patterns to ignore */
+    ignore?: string[];
+}
+/**
+ * Finds files matching a glob pattern.
+ */
+export declare function executeGlob(input: GlobInput, ctx: ToolContext): Promise<ToolResult>;
+export interface GrepInput {
+    pattern: string;
+    path?: string;
+    /** Glob pattern to filter files */
+    glob?: string;
+    /** Case insensitive search */
+    ignoreCase?: boolean;
+}
+export interface GrepMatch {
+    file: string;
+    line: number;
+    content: string;
+}
+/**
+ * Searches for a pattern in files.
+ */
+export declare function executeGrep(input: GrepInput, ctx: ToolContext): Promise<ToolResult>;