@hemansubedi/aether-ai 1.0.0

package/src/tools/filesystem.ts

@@ -0,0 +1,258 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { execSync } from "node:child_process";
+import type { ToolDef } from "../types.js";
+import { Checkpoint } from "../checkpoint.js";
+
+export interface ToolFactory {
+  def: ToolDef;
+  execute: (args: Record<string, any>) => Promise<string>;
+}
+
+const MAX_READ_CHARS = 50_000;
+const MAX_OUTPUT_CHARS = 30_000;
+
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return (
+    s.slice(0, max) +
+    `\n\n[...truncated ${s.length - max} more characters...]\n`
+  );
+}
+
+export function makeReadFileTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "ReadFile",
+      description:
+        "Read the contents of a file at a given relative path. Returns file contents.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: {
+            type: "string",
+            description: "relative path from project root",
+          },
+        },
+        required: ["path"],
+      },
+    },
+    execute: async (args) => {
+      const rel = String(args.path ?? "");
+      const target = path.resolve(rootDir, rel);
+      if (!target.startsWith(path.resolve(rootDir))) {
+        return `ERROR: path "${rel}" escapes the project root`;
+      }
+      try {
+        if (!fs.existsSync(target)) {
+          return `ERROR: file not found: ${rel}`;
+        }
+        if (fs.statSync(target).isDirectory()) {
+          return `ERROR: path "${rel}" is a directory, not a file`;
+        }
+        const content = fs.readFileSync(target, "utf8");
+        return truncate(content, MAX_READ_CHARS);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR reading "${rel}": ${message}`;
+      }
+    },
+  };
+}
+
+export function makeWriteFileTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "WriteFile",
+      description:
+        "Write content to a file, creating parent directories if needed. Returns confirmation.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["path", "content"],
+      },
+    },
+    execute: async (args) => {
+      const rel = String(args.path ?? "");
+      const content = String(args.content ?? "");
+      const target = path.resolve(rootDir, rel);
+      if (!target.startsWith(path.resolve(rootDir))) {
+        return `ERROR: path "${rel}" escapes the project root`;
+      }
+      try {
+        try { Checkpoint.instance().autoCheckpoint(rootDir, rel); } catch {}
+        const parent = path.dirname(target);
+        fs.mkdirSync(parent, { recursive: true });
+        fs.writeFileSync(target, content, "utf8");
+        return `Wrote ${Buffer.byteLength(content, "utf8")} bytes to ${rel}`;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR writing "${rel}": ${message}`;
+      }
+    },
+  };
+}
+
+export function makeEditFileTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "EditFile",
+      description:
+        "Replace exact text in a file. oldText must match exactly once. Returns confirmation.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          oldText: { type: "string" },
+          newText: { type: "string" },
+        },
+        required: ["path", "oldText", "newText"],
+      },
+    },
+    execute: async (args) => {
+      const rel = String(args.path ?? "");
+      const oldText = String(args.oldText ?? "");
+      const newText = String(args.newText ?? "");
+      const target = path.resolve(rootDir, rel);
+      if (!target.startsWith(path.resolve(rootDir))) {
+        return `ERROR: path "${rel}" escapes the project root`;
+      }
+      try {
+        if (!fs.existsSync(target)) {
+          return `ERROR: file not found: ${rel}`;
+        }
+        try { Checkpoint.instance().autoCheckpoint(rootDir, rel); } catch {}
+        const original = fs.readFileSync(target, "utf8");
+        const first = original.indexOf(oldText);
+        if (first === -1) {
+          return `ERROR: oldText not found in "${rel}". The file may have changed; read it first.`;
+        }
+        const second = original.indexOf(oldText, first + 1);
+        if (second !== -1) {
+          return `ERROR: oldText found multiple times in "${rel}". oldText must match exactly once.`;
+        }
+        const updated =
+          original.slice(0, first) +
+          newText +
+          original.slice(first + oldText.length);
+        fs.writeFileSync(target, updated, "utf8");
+        return `Edited ${rel}: ${countLines(oldText)} old line(s) -> ${countLines(newText)} new line(s)`;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR editing "${rel}": ${message}`;
+      }
+    },
+  };
+}
+
+function countLines(s: string): number {
+  if (s.length === 0) return 0;
+  return s.split("\n").length;
+}
+
+export function makeListDirTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "ListDir",
+      description:
+        "List files and subdirectories at a path (recursive, like tree).",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", default: "." },
+        },
+      },
+    },
+    execute: async (args) => {
+      const rel = String(args.path ?? ".");
+      const target = path.resolve(rootDir, rel);
+      if (!target.startsWith(path.resolve(rootDir))) {
+        return `ERROR: path "${rel}" escapes the project root`;
+      }
+      try {
+        if (!fs.existsSync(target)) {
+          return `ERROR: path not found: ${rel}`;
+        }
+        const lines: string[] = [];
+        const rootLabel = rel === "." ? "." : rel;
+        lines.push(rootLabel);
+        walk(target, "", lines);
+        return truncate(lines.join("\n"), MAX_OUTPUT_CHARS);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR listing "${rel}": ${message}`;
+      }
+    },
+  };
+}
+
+function walk(dir: string, prefix: string, lines: string[]): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const filtered = entries.filter((e) => !e.name.startsWith("."));
+  filtered.forEach((entry, i) => {
+    const isLast = i === filtered.length - 1;
+    const connector = isLast ? "+-- " : "+-- ";
+    lines.push(`${prefix}${connector}${entry.name}`);
+    if (entry.isDirectory()) {
+      walk(path.join(dir, entry.name), prefix + (isLast ? "    " : "�   "), lines);
+    }
+  });
+}
+
+export function makeBashTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "Bash",
+      description:
+        "Execute a shell command in the project directory. Returns stdout+stderr. Use for running commands, tests, installs. Prefer non-interactive commands.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "the shell command",
+          },
+          timeoutMs: { type: "number", default: 30000 },
+        },
+        required: ["command"],
+      },
+    },
+    execute: async (args) => {
+      const command = String(args.command ?? "");
+      if (!command.trim()) {
+        return "ERROR: empty command";
+      }
+      const timeoutMs = Math.max(
+        1000,
+        Math.min(600_000, Number(args.timeoutMs) || 30_000)
+      );
+      try {
+        const stdout = execSync(command, {
+          cwd: rootDir,
+          maxBuffer: 10 * 1024 * 1024,
+          timeout: timeoutMs,
+          encoding: "utf8",
+          stdio: ["ignore", "pipe", "pipe"],
+        });
+        return truncate(stdout, MAX_OUTPUT_CHARS);
+      } catch (err: any) {
+        const stderr = err?.stderr ? String(err.stderr) : "";
+        const message = err?.message ? String(err.message) : String(err);
+        const stdout = err?.stdout ? String(err.stdout) : "";
+        return truncate(
+          `ERROR: ${stderr || message}\nSTDOUT: ${stdout}`,
+          MAX_OUTPUT_CHARS
+        );
+      }
+    },
+  };
+}

package/src/tools/git.ts

@@ -0,0 +1,53 @@
+import * as path from "node:path";
+import { GitTool } from "../git.js";
+
+export function makeGitTool(rootDir: string) {
+  return {
+    def: {
+      name: "Git",
+      description: "Run git operations: status, diff, commit, log, branch. Use this to inspect version control state or make commits.",
+      parameters: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["status", "diff", "commit", "log", "branch"], description: "The git operation to perform" },
+          message: { type: "string", description: "Commit message (required for commit)" },
+          file: { type: "string", description: "Optional file path to limit diff" },
+          count: { type: "number", description: "Number of commits to show (for log)", default: 5 }
+        },
+        required: ["action"]
+      }
+    },
+    execute: async (args: Record<string, any>) => {
+      if (!GitTool.isRepo(rootDir)) {
+        return `ERROR: ${rootDir} is not a git repository.`;
+      }
+      try {
+        switch (args.action) {
+          case "status": {
+            const files = await GitTool.status(rootDir);
+            if (files.length === 0) return "Working tree clean.";
+            return files.map((f) => `${f.status}\t${f.file}`).join("\n");
+          }
+          case "diff": {
+            const d = await GitTool.diff(rootDir, args.file);
+            return d || "(no differences)";
+          }
+          case "commit": {
+            return await GitTool.commit(rootDir, args.message || "");
+          }
+          case "log": {
+            const commits = await GitTool.log(rootDir, args.count ?? 5);
+            return commits.map((c) => `${c.hash} ${c.date} ${c.message}`).join("\n");
+          }
+          case "branch": {
+            return `Current branch: ${await GitTool.branch(rootDir)}`;
+          }
+          default:
+            return `ERROR: unknown git action "${args.action}"`;
+        }
+      } catch (err) {
+        return `ERROR: ${(err as Error).message}`;
+      }
+    }
+  };
+}

package/src/tools/glob.ts

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ToolDef } from "../types.js";
+
+export interface ToolFactory {
+  def: ToolDef;
+  execute: (args: Record<string, any>) => Promise<string>;
+}
+
+const MAX_RESULTS = 5000;
+
+/**
+ * Match a single path segment against a glob segment.
+ *  - `*`  matches any characters except `/`
+ *  - `**` matches any number of path segments (including zero)
+ *  - `?`  matches exactly one character except `/`
+ *  - `[...]` character class
+ */
+function matchSegment(segment: string, value: string): boolean {
+  if (segment === "**") return true;
+  if (segment === value) return true;
+
+  // Build a regex from the segment.
+  let re = "";
+  let i = 0;
+  while (i < segment.length) {
+    const ch = segment[i];
+    if (ch === "*") {
+      if (segment[i + 1] === "*") {
+        // `**` within a segment means match anything including /
+        re += ".*";
+        i += 2;
+        continue;
+      }
+      re += "[^/]*";
+      i += 1;
+      continue;
+    }
+    if (ch === "?") {
+      re += "[^/]";
+      i += 1;
+      continue;
+    }
+    if (ch === "[") {
+      let j = i + 1;
+      if (j < segment.length && segment[j] === "!") j++;
+      if (j < segment.length && segment[j] === "]") j++;
+      while (j < segment.length && segment[j] !== "]") j++;
+      if (j >= segment.length) {
+        // No closing bracket - treat literally.
+        re += "\\[";
+        i += 1;
+        continue;
+      }
+      let cls = segment.slice(i + 1, j);
+      if (cls.startsWith("!")) cls = "^" + cls.slice(1);
+      re += "[" + cls + "]";
+      i = j + 1;
+      continue;
+    }
+    re += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    i += 1;
+  }
+  return new RegExp("^" + re + "$").test(value);
+}
+
+function splitPattern(pattern: string): string[] {
+  return pattern.replace(/\\/g, "/").replace(/^\.\//, "").split("/").filter((s) => s !== "");
+}
+
+function* walkMatches(
+  segments: string[],
+  prefix: string,
+  cwd: string,
+  depth: number
+): Generator<string> {
+  const seg = segments[depth];
+  const isLast = depth === segments.length - 1;
+
+  if (seg === "**") {
+    // `**` matches the current directory and any depth below it.
+    if (isLast) {
+      yield prefix;
+    }
+    // Recurse into the current directory.
+    yield* walkMatches(segments, prefix, cwd, depth + 1);
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(cwd, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name.startsWith(".")) continue;
+      const sub = path.join(cwd, e.name);
+      const rel = prefix ? prefix + "/" + e.name : e.name;
+      if (e.isDirectory()) {
+        yield* walkMatches(segments, rel, sub, depth);
+      } else if (isLast) {
+        yield rel;
+      }
+    }
+    return;
+  }
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    if (!matchSegment(seg, e.name)) continue;
+    const sub = path.join(cwd, e.name);
+    const rel = prefix ? prefix + "/" + e.name : e.name;
+    if (isLast) {
+      yield rel;
+    } else if (e.isDirectory()) {
+      yield* walkMatches(segments, rel, sub, depth + 1);
+    }
+  }
+}
+
+export function makeGlobTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "Glob",
+      description:
+        "Find files matching a glob pattern (e.g. **/*.ts, src/*.js). Returns matching paths relative to project root, sorted.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: {
+            type: "string",
+            description: "glob pattern like **/*.ts",
+          },
+          path: {
+            type: "string",
+            default: ".",
+            description: "root dir to search",
+          },
+        },
+        required: ["pattern"],
+      },
+    },
+    execute: async (args) => {
+      const pattern = String(args.pattern ?? "").trim();
+      if (!pattern) {
+        return "ERROR: pattern is required";
+      }
+      const relRoot = String(args.path ?? ".").trim() || ".";
+      const target = path.resolve(rootDir, relRoot);
+      if (!target.startsWith(path.resolve(rootDir))) {
+        return `ERROR: path "${relRoot}" escapes the project root`;
+      }
+      try {
+        if (!fs.existsSync(target)) {
+          return `ERROR: path not found: ${relRoot}`;
+        }
+        const segments = splitPattern(pattern);
+        if (segments.length === 0) {
+          return "ERROR: empty pattern";
+        }
+        const results: string[] = [];
+        for (const match of walkMatches(segments, "", target, 0)) {
+          results.push(match);
+          if (results.length >= MAX_RESULTS) break;
+        }
+        results.sort();
+        if (results.length === 0) return "No matches";
+        return results.join("\n");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR globbing "${pattern}": ${message}`;
+      }
+    },
+  };
+}

package/src/tools/grep.ts

@@ -0,0 +1,192 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ToolDef } from "../types.js";
+
+export interface ToolFactory {
+  def: ToolDef;
+  execute: (args: Record<string, any>) => Promise<string>;
+}
+
+const MAX_RESULTS = 5000;
+const MAX_LINE_CHARS = 5000;
+
+function matchesInclude(name: string, include: string): boolean {
+  if (!include) return true;
+  const patterns = include.split(",").map((s) => s.trim()).filter(Boolean);
+  for (const pat of patterns) {
+    if (matchGlob(pat, name)) return true;
+  }
+  return false;
+}
+
+function matchGlob(pattern: string, value: string): boolean {
+  const re = globToRegex(pattern);
+  return re.test(value);
+}
+
+function globToRegex(pattern: string): RegExp {
+  let re = "";
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === "*") {
+      if (pattern[i + 1] === "*") {
+        re += ".*";
+        i += 2;
+        continue;
+      }
+      re += "[^/]*";
+      i += 1;
+      continue;
+    }
+    if (ch === "?") {
+      re += "[^/]";
+      i += 1;
+      continue;
+    }
+    if (ch === "[") {
+      let j = i + 1;
+      if (j < pattern.length && pattern[j] === "!") j++;
+      if (j < pattern.length && pattern[j] === "]") j++;
+      while (j < pattern.length && pattern[j] !== "]") j++;
+      if (j >= pattern.length) {
+        re += "\\[";
+        i += 1;
+        continue;
+      }
+      let cls = pattern.slice(i + 1, j);
+      if (cls.startsWith("!")) cls = "^" + cls.slice(1);
+      re += "[" + cls + "]";
+      i = j + 1;
+      continue;
+    }
+    re += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    i += 1;
+  }
+  return new RegExp("^" + re + "$");
+}
+
+function isBinary(buf: Buffer): boolean {
+  // Detect null bytes (common in binary files).
+  for (let i = 0; i < Math.min(buf.length, 4096); i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+function* walkFiles(dir: string): Generator<string> {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".")) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (e.isFile()) {
+      yield full;
+    }
+  }
+}
+
+export function makeGrepTool(rootDir: string): ToolFactory {
+  return {
+    def: {
+      name: "Grep",
+      description:
+        "Search file contents for a regex pattern. Returns matching lines with file path and line number. Use include filter like *.ts.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: {
+            type: "string",
+            description: "regex pattern",
+          },
+          path: {
+            type: "string",
+            default: ".",
+            description: "dir or file to search",
+          },
+          include: {
+            type: "string",
+            default: "",
+            description: "file filter e.g. *.ts",
+          },
+          maxResults: {
+            type: "number",
+            default: 50,
+          },
+        },
+        required: ["pattern"],
+      },
+    },
+    execute: async (args) => {
+      const pattern = String(args.pattern ?? "");
+      if (!pattern) {
+        return "ERROR: pattern is required";
+      }
+      let regex: RegExp;
+      try {
+        regex = new RegExp(pattern);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR: invalid regex: ${message}`;
+      }
+
+      const relPath = String(args.path ?? ".").trim() || ".";
+      const target = path.resolve(rootDir, relPath);
+      if (!target.startsWith(path.resolve(rootDir))) {
+        return `ERROR: path "${relPath}" escapes the project root`;
+      }
+      const include = String(args.include ?? "");
+      const maxResults = Math.max(1, Math.min(MAX_RESULTS, Number(args.maxResults) || 50));
+
+      try {
+        if (!fs.existsSync(target)) {
+          return `ERROR: path not found: ${relPath}`;
+        }
+
+        const files: string[] = [];
+        if (fs.statSync(target).isFile()) {
+          files.push(target);
+        } else {
+          for (const f of walkFiles(target)) {
+            files.push(f);
+          }
+        }
+
+        const matches: string[] = [];
+        for (const full of files) {
+          const rel = path.relative(rootDir, full).replace(/\\/g, "/");
+          if (!matchesInclude(rel, include)) continue;
+          try {
+            const buf = fs.readFileSync(full);
+            if (isBinary(buf)) continue;
+            const text = buf.toString("utf8");
+            const lines = text.split("\n");
+            for (let ln = 1; ln <= lines.length; ln++) {
+              if (matches.length >= maxResults) break;
+              const line = lines[ln - 1];
+              if (line.length > MAX_LINE_CHARS) continue;
+              if (regex.test(line)) {
+                matches.push(`${rel}:${ln}: ${line}`);
+              }
+            }
+          } catch {
+            // skip unreadable files
+          }
+          if (matches.length >= maxResults) break;
+        }
+
+        if (matches.length === 0) return "No matches";
+        return matches.join("\n");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR grepping "${pattern}": ${message}`;
+      }
+    },
+  };
+}