@mewbleh/purrx 1.0.8

package/src/platform.js

@@ -0,0 +1,94 @@
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { exec } from "node:child_process";
+
+// Detects the platform purrx is running on, with special handling for Termux
+// on Android (which reports as linux but has its own conventions).
+export function detectPlatform() {
+  const p = process.platform;
+  if (p === "win32") return "windows";
+  if (p === "darwin") return "macos";
+  if (p === "android") return "android"; // newer Node builds
+  if (p === "linux") {
+    if (isTermux()) return "android";
+    return "linux";
+  }
+  return p;
+}
+
+export function isTermux() {
+  if (process.env.TERMUX_VERSION) return true;
+  const prefix = process.env.PREFIX || "";
+  if (prefix.includes("com.termux")) return true;
+  try {
+    return fs.existsSync("/data/data/com.termux/files/usr");
+  } catch {
+    return false;
+  }
+}
+
+// Returns the base directory where purrx stores its data (credentials,
+// sessions). Honours overrides and falls back to OS-appropriate locations.
+export function dataHome() {
+  if (process.env.PURRX_HOME) return process.env.PURRX_HOME;
+  if (process.env.CODEX_HOME) return process.env.CODEX_HOME;
+
+  const platform = detectPlatform();
+  if (platform === "windows") {
+    const base =
+      process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+    return path.join(base, "purrx");
+  }
+  if (platform === "macos") {
+    return path.join(os.homedir(), "Library", "Application Support", "purrx");
+  }
+  // linux / android (termux): respect XDG, default to ~/.purrx
+  const xdg = process.env.XDG_DATA_HOME;
+  if (xdg) return path.join(xdg, "purrx");
+  return path.join(os.homedir(), ".purrx");
+}
+
+// Returns the appropriate default shell command runner for the platform.
+export function shellFor(command) {
+  const platform = detectPlatform();
+  if (platform === "windows") {
+    // Use cmd.exe via the default exec shell.
+    return { command, shell: process.env.ComSpec || "cmd.exe" };
+  }
+  // POSIX-like (linux, macos, termux). Prefer the user's shell, then sh.
+  const shell =
+    process.env.SHELL ||
+    (platform === "android"
+      ? path.join(process.env.PREFIX || "/data/data/com.termux/files/usr", "bin/bash")
+      : "/bin/sh");
+  return { command, shell };
+}
+
+// Opens a URL in the user's browser across platforms.
+export function openBrowser(url) {
+  const platform = detectPlatform();
+  let cmd;
+  switch (platform) {
+    case "windows":
+      cmd = `start "" "${url}"`;
+      break;
+    case "macos":
+      cmd = `open "${url}"`;
+      break;
+    case "android":
+      // Termux provides termux-open-url (from termux-api). Fall back to xdg-open.
+      cmd = `termux-open-url "${url}" || xdg-open "${url}"`;
+      break;
+    default:
+      cmd = `xdg-open "${url}"`;
+  }
+  exec(cmd, () => {});
+}
+
+// Whether ANSI colors should be used. Disabled when NO_COLOR is set or output
+// is not a TTY.
+export function colorsEnabled() {
+  if (process.env.NO_COLOR) return false;
+  return Boolean(process.stdout.isTTY);
+}

package/src/tools/builtin.js

@@ -0,0 +1,476 @@
+import fs from "node:fs";
+import path from "node:path";
+import { exec } from "node:child_process";
+import { shellFor } from "../platform.js";
+import { saveMemory, readSkill, listSkills } from "../core/context.js";
+
+// ---------------------------------------------------------------------------
+// Built-in tool definitions (OpenAI Responses "function" tool format).
+// ---------------------------------------------------------------------------
+
+/** @type {import("../types.js").ToolDefinition[]} */
+export const toolDefinitions = [
+  {
+    type: "function",
+    name: "read_file",
+    description:
+      "Read the contents of a text file. Optionally read a line range.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file to read." },
+        start_line: {
+          type: "integer",
+          description: "Optional 1-based start line.",
+        },
+        end_line: { type: "integer", description: "Optional 1-based end line." },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "write_file",
+    description: "Create or overwrite a text file with the provided content.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file to write." },
+        content: { type: "string", description: "Full file content." },
+      },
+      required: ["path", "content"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "edit_file",
+    description:
+      "Replace an exact substring in a file with new text. The old_text must match exactly once. Use for surgical edits without rewriting the whole file.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to the file to edit." },
+        old_text: {
+          type: "string",
+          description: "Exact text to find (must be unique in the file).",
+        },
+        new_text: { type: "string", description: "Replacement text." },
+      },
+      required: ["path", "old_text", "new_text"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "list_directory",
+    description: "List files and folders in a directory.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: {
+          type: "string",
+          description: "Directory path. Defaults to the current directory.",
+        },
+      },
+      required: [],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "search_files",
+    description:
+      "Recursively search file contents for a regular expression. Returns matching lines with file paths and line numbers.",
+    parameters: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Regular expression to search for." },
+        path: {
+          type: "string",
+          description: "Directory to search in. Defaults to current directory.",
+        },
+        glob: {
+          type: "string",
+          description:
+            "Optional filename glob filter, e.g. '*.js' or '*.{ts,tsx}'.",
+        },
+      },
+      required: ["pattern"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "find_files",
+    description:
+      "Find files by name using a glob pattern (e.g. '**/*.js'). Returns matching paths.",
+    parameters: {
+      type: "object",
+      properties: {
+        glob: { type: "string", description: "Glob pattern to match file paths." },
+        path: {
+          type: "string",
+          description: "Base directory. Defaults to current directory.",
+        },
+      },
+      required: ["glob"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "delete_file",
+    description: "Delete a file or empty directory.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Path to delete." },
+      },
+      required: ["path"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "run_command",
+    description:
+      "Run a shell command in the working directory and return stdout/stderr.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to run." },
+      },
+      required: ["command"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "fetch_url",
+    description:
+      "Fetch the contents of an HTTP(S) URL. Returns the response body as text (truncated if large).",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The https:// URL to fetch." },
+      },
+      required: ["url"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "remember",
+    description:
+      "Save a durable note to long-term memory so it persists across sessions. Use for user preferences, project conventions, or facts worth recalling later. Do not store secrets.",
+    parameters: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "The note to remember." },
+        topic: {
+          type: "string",
+          description:
+            "Optional topic/file to group the note under (e.g. 'preferences', 'project'). Defaults to 'notes'.",
+        },
+      },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "use_skill",
+    description:
+      "Load the full playbook for a named skill before performing a task. Skills are reusable instructions. Call list_skills first if unsure which exist.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The skill name to load." },
+      },
+      required: ["name"],
+      additionalProperties: false,
+    },
+  },
+  {
+    type: "function",
+    name: "list_skills",
+    description: "List the skills available in this project and globally.",
+    parameters: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false,
+    },
+  },
+];
+
+// Tools that only read state (used by the approval layer).
+export const READ_ONLY_TOOLS = new Set([
+  "read_file",
+  "list_directory",
+  "search_files",
+  "find_files",
+  "fetch_url",
+  "use_skill",
+  "list_skills",
+]);
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const MAX_OUTPUT = 100_000;
+const IGNORE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  ".cache",
+  "coverage",
+]);
+
+function truncate(text) {
+  return text.length > MAX_OUTPUT
+    ? text.slice(0, MAX_OUTPUT) + "\n...[truncated]"
+    : text;
+}
+
+// Converts a glob to a RegExp (supports *, **, ?, {a,b}).
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++;
+      } else {
+        re += "[^/]*";
+      }
+    } else if (ch === "?") {
+      re += "[^/]";
+    } else if (ch === "{") {
+      const end = glob.indexOf("}", i);
+      const opts = glob.slice(i + 1, end).split(",");
+      re += "(" + opts.map(escapeRe).join("|") + ")";
+      i = end;
+    } else {
+      re += escapeRe(ch);
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+function escapeRe(s) {
+  return s.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}
+
+function* walk(dir, base = dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".") && e.name !== ".") {
+      if (IGNORE_DIRS.has(e.name)) continue;
+    }
+    if (IGNORE_DIRS.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walk(full, base);
+    } else {
+      yield full;
+    }
+  }
+}
+
+function runCommand(command, cwd) {
+  return new Promise((resolve) => {
+    const { shell } = shellFor(command);
+    exec(
+      command,
+      { cwd, shell, maxBuffer: 10 * 1024 * 1024, windowsHide: true },
+      (error, stdout, stderr) => {
+        const out = (stdout || "").trim();
+        const err = (stderr || "").trim();
+        let result = "";
+        if (out) result += out;
+        if (err) result += (result ? "\n" : "") + `[stderr]\n${err}`;
+        if (error && typeof error.code === "number") {
+          result += `\n[exit code: ${error.code}]`;
+        }
+        resolve(truncate(result || "(no output)"));
+      }
+    );
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Tool execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a built-in tool by name.
+ * @param {string} name
+ * @param {Record<string, any>} args
+ * @param {string} [cwd]
+ * @returns {Promise<string>}
+ */
+export async function executeTool(name, args, cwd = process.cwd()) {
+  try {
+    switch (name) {
+      case "read_file": {
+        const p = path.resolve(cwd, args.path);
+        let content = fs.readFileSync(p, "utf8");
+        if (args.start_line || args.end_line) {
+          const lines = content.split("\n");
+          const start = Math.max(1, args.start_line || 1);
+          const end = Math.min(lines.length, args.end_line || lines.length);
+          content = lines
+            .slice(start - 1, end)
+            .map((l, idx) => `${start + idx}\t${l}`)
+            .join("\n");
+        }
+        return truncate(content);
+      }
+
+      case "write_file": {
+        const p = path.resolve(cwd, args.path);
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, args.content, "utf8");
+        return `Wrote ${Buffer.byteLength(args.content)} bytes to ${args.path}`;
+      }
+
+      case "edit_file": {
+        const p = path.resolve(cwd, args.path);
+        const content = fs.readFileSync(p, "utf8");
+        const count = content.split(args.old_text).length - 1;
+        if (count === 0) {
+          return `Error: old_text not found in ${args.path}`;
+        }
+        if (count > 1) {
+          return `Error: old_text matches ${count} times in ${args.path}; make it more specific so it is unique.`;
+        }
+        const updated = content.replace(args.old_text, args.new_text);
+        fs.writeFileSync(p, updated, "utf8");
+        return `Edited ${args.path} (1 replacement).`;
+      }
+
+      case "list_directory": {
+        const p = path.resolve(cwd, args.path || ".");
+        const entries = fs.readdirSync(p, { withFileTypes: true });
+        return (
+          entries
+            .map((e) => (e.isDirectory() ? `${e.name}/` : e.name))
+            .sort()
+            .join("\n") || "(empty directory)"
+        );
+      }
+
+      case "search_files": {
+        const base = path.resolve(cwd, args.path || ".");
+        let re;
+        try {
+          re = new RegExp(args.pattern);
+        } catch (err) {
+          return `Error: invalid regex: ${err.message}`;
+        }
+        const globRe = args.glob ? globToRegExp(args.glob) : null;
+        const matches = [];
+        for (const file of walk(base)) {
+          const rel = path.relative(cwd, file).replace(/\\/g, "/");
+          if (globRe && !globRe.test(path.basename(file)) && !globRe.test(rel)) {
+            continue;
+          }
+          let text;
+          try {
+            text = fs.readFileSync(file, "utf8");
+          } catch {
+            continue;
+          }
+          const lines = text.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            if (re.test(lines[i])) {
+              matches.push(`${rel}:${i + 1}: ${lines[i].trim()}`);
+              if (matches.length >= 200) break;
+            }
+          }
+          if (matches.length >= 200) break;
+        }
+        return matches.length
+          ? truncate(matches.join("\n"))
+          : "(no matches)";
+      }
+
+      case "find_files": {
+        const base = path.resolve(cwd, args.path || ".");
+        const globRe = globToRegExp(args.glob);
+        const found = [];
+        for (const file of walk(base)) {
+          const rel = path.relative(base, file).replace(/\\/g, "/");
+          if (globRe.test(rel) || globRe.test(path.basename(file))) {
+            found.push(path.relative(cwd, file).replace(/\\/g, "/"));
+            if (found.length >= 500) break;
+          }
+        }
+        return found.length ? found.join("\n") : "(no files matched)";
+      }
+
+      case "delete_file": {
+        const p = path.resolve(cwd, args.path);
+        fs.rmSync(p, { recursive: false });
+        return `Deleted ${args.path}`;
+      }
+
+      case "run_command": {
+        return await runCommand(args.command, cwd);
+      }
+
+      case "fetch_url": {
+        if (!/^https?:\/\//i.test(args.url)) {
+          return "Error: only http(s) URLs are supported.";
+        }
+        const resp = await fetch(args.url, {
+          headers: { "User-Agent": "purrx-agent" },
+        });
+        const text = await resp.text();
+        return truncate(`[status ${resp.status}]\n${text}`);
+      }
+
+      case "remember": {
+        const file = saveMemory(args.text, args.topic || "notes");
+        return `Saved to memory (${path.basename(file)}).`;
+      }
+
+      case "use_skill": {
+        const body = readSkill(cwd, args.name);
+        if (!body) {
+          const available = listSkills(cwd)
+            .map((s) => s.name)
+            .join(", ");
+          return `Error: no skill named "${args.name}". Available: ${available || "(none)"}`;
+        }
+        return body;
+      }
+
+      case "list_skills": {
+        const skills = listSkills(cwd);
+        if (!skills.length) return "(no skills available)";
+        return skills
+          .map((s) => `${s.name}: ${s.description || "(no description)"}`)
+          .join("\n");
+      }
+
+      default:
+        return `Error: unknown tool "${name}"`;
+    }
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+}