sentinelayer-cli 0.4.4 → 0.6.2

package/src/agents/shared-tools/glob.js

@@ -0,0 +1,168 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const MAX_RESULTS = 200;
+const IGNORE_DIRS = new Set([
+  ".git", "node_modules", ".next", "dist", "build", "coverage",
+  ".turbo", ".idea", ".vscode", "__pycache__", ".venv", ".cache",
+  ".parcel-cache", ".svelte-kit", ".nuxt", ".output", ".vercel",
+]);
+
+/**
+ * Fast file pattern matching sorted by modification time (newest first).
+ *
+ * @param {object} input
+ * @param {string} input.pattern - Glob pattern (e.g., "**\/*.tsx", "src/**\/*.js").
+ * @param {string} [input.path] - Directory to search (default: cwd).
+ * @param {number} [input.limit] - Max results (default: 200).
+ * @returns {{ filenames, numFiles, truncated, durationMs }}
+ */
+export function glob(input) {
+  if (!input.pattern || typeof input.pattern !== "string") {
+    throw new GlobError("pattern is required and must be a non-empty string.");
+  }
+
+  const searchPath = input.path ? path.resolve(input.path) : process.cwd();
+  const limit = input.limit ?? MAX_RESULTS;
+  const startMs = Date.now();
+
+  if (!fs.existsSync(searchPath)) {
+    throw new GlobError(`Directory not found: ${searchPath}`);
+  }
+
+  const stat = fs.statSync(searchPath);
+  if (!stat.isDirectory()) {
+    throw new GlobError(`Path is not a directory: ${searchPath}`);
+  }
+
+  const matcher = buildMatcher(input.pattern);
+  const ignorePatterns = loadIgnorePatterns(searchPath);
+  const results = [];
+
+  walk(searchPath, searchPath, matcher, ignorePatterns, results, limit);
+
+  // Sort by mtime descending (newest first)
+  results.sort((a, b) => b.mtime - a.mtime);
+
+  const truncated = results.length >= limit;
+  const filenames = results.map((r) => r.relativePath);
+
+  return {
+    filenames,
+    numFiles: filenames.length,
+    truncated,
+    durationMs: Date.now() - startMs,
+  };
+}
+
+function walk(rootPath, currentPath, matcher, ignorePatterns, results, limit) {
+  let entries;
+  try {
+    entries = fs.readdirSync(currentPath, { withFileTypes: true });
+  } catch {
+    return; // skip unreadable directories
+  }
+
+  for (const entry of entries) {
+    if (results.length >= limit) return;
+
+    const name = entry.name;
+    if (IGNORE_DIRS.has(name)) continue;
+
+    const fullPath = path.join(currentPath, name);
+    const relativePath = path.relative(rootPath, fullPath);
+
+    if (ignorePatterns.some((p) => p(relativePath))) continue;
+
+    if (entry.isDirectory()) {
+      walk(rootPath, fullPath, matcher, ignorePatterns, results, limit);
+    } else if (entry.isFile() && matcher(relativePath)) {
+      let mtime = 0;
+      try {
+        mtime = fs.statSync(fullPath).mtimeMs;
+      } catch { /* use 0 if stat fails */ }
+      results.push({ relativePath, mtime });
+    }
+  }
+}
+
+/**
+ * Build a filename matcher from a glob pattern.
+ * Supports: *.ext, **\/*.ext, *.{ext1,ext2}, prefix*, *suffix
+ */
+function buildMatcher(pattern) {
+  // Handle brace expansion: *.{ts,tsx} → ["*.ts", "*.tsx"]
+  const expanded = expandBraces(pattern);
+
+  const matchers = expanded.map((p) => {
+    // ** recursive match
+    if (p.includes("**/")) {
+      const suffix = p.split("**/").pop();
+      const suffixMatcher = buildSimpleMatcher(suffix);
+      return (filepath) => {
+        const basename = path.basename(filepath);
+        const segments = filepath.split(path.sep);
+        return segments.some((_, i) =>
+          suffixMatcher(segments.slice(i).join(path.sep)),
+        ) || suffixMatcher(basename);
+      };
+    }
+    return buildSimpleMatcher(p);
+  });
+
+  return (filepath) => matchers.some((m) => m(filepath));
+}
+
+function buildSimpleMatcher(pattern) {
+  if (pattern.startsWith("*.")) {
+    const ext = pattern.slice(1);
+    return (filepath) => filepath.endsWith(ext) || path.basename(filepath).endsWith(ext);
+  }
+  if (pattern.endsWith("*")) {
+    const prefix = pattern.slice(0, -1);
+    return (filepath) => filepath.startsWith(prefix) || path.basename(filepath).startsWith(prefix);
+  }
+  if (pattern.includes("*")) {
+    const regex = new RegExp(
+      "^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$",
+    );
+    return (filepath) => regex.test(filepath) || regex.test(path.basename(filepath));
+  }
+  return (filepath) => filepath === pattern || path.basename(filepath) === pattern;
+}
+
+function expandBraces(pattern) {
+  const braceMatch = pattern.match(/\{([^}]+)\}/);
+  if (!braceMatch) return [pattern];
+  const alternatives = braceMatch[1].split(",");
+  return alternatives.map((alt) =>
+    pattern.replace(braceMatch[0], alt.trim()),
+  );
+}
+
+function loadIgnorePatterns(rootPath) {
+  const patterns = [];
+  const gitignorePath = path.join(rootPath, ".gitignore");
+  const slignorePath = path.join(rootPath, ".sentinelayerignore");
+
+  for (const ignorePath of [gitignorePath, slignorePath]) {
+    try {
+      const content = fs.readFileSync(ignorePath, "utf-8");
+      for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) continue;
+        const matcher = buildSimpleMatcher(trimmed);
+        patterns.push(matcher);
+      }
+    } catch { /* ignore missing files */ }
+  }
+
+  return patterns;
+}
+
+export class GlobError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GlobError";
+  }
+}

package/src/agents/shared-tools/grep.js

@@ -0,0 +1,228 @@
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+const DEFAULT_HEAD_LIMIT = 250;
+const MAX_LINE_LENGTH = 500;
+const VCS_EXCLUDE_DIRS = [
+  ".git", ".svn", ".hg", "node_modules", ".next", "dist", "build",
+  "coverage", ".turbo", ".idea", ".vscode", "__pycache__", ".venv",
+];
+
+/**
+ * Search file contents using ripgrep.
+ * Falls back to a naive line-by-line search if rg is not installed.
+ *
+ * @param {object} input
+ * @param {string} input.pattern - Regex pattern to search for.
+ * @param {string} [input.path] - Directory to search (default: cwd).
+ * @param {string} [input.glob] - Glob filter (e.g., "*.tsx").
+ * @param {string} [input.output_mode] - "content" | "files_with_matches" | "count"
+ * @param {number} [input.context] - Lines of context before and after match.
+ * @param {boolean} [input.case_insensitive] - Case-insensitive search.
+ * @param {number} [input.head_limit] - Max results (default 250).
+ * @param {boolean} [input.multiline] - Enable multiline matching.
+ * @returns {{ mode, numFiles, filenames, content, numMatches, appliedLimit }}
+ */
+export function grep(input) {
+  if (!input.pattern || typeof input.pattern !== "string") {
+    throw new GrepError("pattern is required and must be a non-empty string.");
+  }
+
+  const searchPath = input.path ? path.resolve(input.path) : process.cwd();
+  const outputMode = input.output_mode || "files_with_matches";
+  const headLimit = input.head_limit ?? DEFAULT_HEAD_LIMIT;
+
+  const args = buildRgArgs(input, searchPath, outputMode);
+
+  let stdout;
+  try {
+    stdout = execFileSync("rg", args, {
+      cwd: searchPath,
+      encoding: "utf-8",
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: 30_000,
+    });
+  } catch (err) {
+    // rg exits with code 1 when no matches found — that's normal
+    if (err.status === 1) {
+      return {
+        mode: outputMode,
+        numFiles: 0,
+        filenames: [],
+        content: "",
+        numMatches: 0,
+        appliedLimit: headLimit,
+      };
+    }
+    // rg not installed — fall back to naive search
+    if (err.code === "ENOENT") {
+      return naiveFallbackGrep(input, searchPath, outputMode, headLimit);
+    }
+    throw new GrepError(`ripgrep failed: ${err.message}`);
+  }
+
+  return parseRgOutput(stdout, outputMode, headLimit);
+}
+
+function buildRgArgs(input, searchPath, outputMode) {
+  const args = ["--no-heading", "--color", "never"];
+
+  // Output mode flags
+  if (outputMode === "files_with_matches") {
+    args.push("-l");
+  } else if (outputMode === "count") {
+    args.push("-c");
+  } else {
+    args.push("-n"); // line numbers for content mode
+  }
+
+  // Context
+  if (input.context && outputMode === "content") {
+    args.push("-C", String(input.context));
+  }
+
+  // Case insensitive
+  if (input.case_insensitive) {
+    args.push("-i");
+  }
+
+  // Multiline
+  if (input.multiline) {
+    args.push("-U", "--multiline-dotall");
+  }
+
+  // Glob filter
+  if (input.glob) {
+    args.push("--glob", input.glob);
+  }
+
+  // Exclude VCS and build directories
+  for (const dir of VCS_EXCLUDE_DIRS) {
+    args.push("--glob", `!${dir}`);
+  }
+
+  // Max line length to prevent base64/minified content noise
+  args.push("--max-columns", String(MAX_LINE_LENGTH));
+  args.push("--max-columns-preview");
+
+  args.push("--", input.pattern, searchPath);
+  return args;
+}
+
+function parseRgOutput(stdout, outputMode, headLimit) {
+  const lines = stdout.split("\n").filter(Boolean);
+  const limited = headLimit > 0 ? lines.slice(0, headLimit) : lines;
+
+  if (outputMode === "files_with_matches") {
+    return {
+      mode: outputMode,
+      numFiles: limited.length,
+      filenames: limited,
+      content: "",
+      numMatches: limited.length,
+      appliedLimit: headLimit,
+    };
+  }
+
+  if (outputMode === "count") {
+    let totalMatches = 0;
+    const filenames = [];
+    for (const line of limited) {
+      const colonIdx = line.lastIndexOf(":");
+      if (colonIdx > 0) {
+        filenames.push(line.slice(0, colonIdx));
+        totalMatches += parseInt(line.slice(colonIdx + 1), 10) || 0;
+      }
+    }
+    return {
+      mode: outputMode,
+      numFiles: filenames.length,
+      filenames,
+      content: limited.join("\n"),
+      numMatches: totalMatches,
+      appliedLimit: headLimit,
+    };
+  }
+
+  // Content mode
+  const fileSet = new Set();
+  for (const line of limited) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx > 0) {
+      fileSet.add(line.slice(0, colonIdx));
+    }
+  }
+  return {
+    mode: outputMode,
+    numFiles: fileSet.size,
+    filenames: [...fileSet],
+    content: limited.join("\n"),
+    numMatches: limited.length,
+    appliedLimit: headLimit,
+  };
+}
+
+/**
+ * Naive line-by-line fallback when ripgrep is not installed.
+ * Significantly slower but functional.
+ */
+function naiveFallbackGrep(input, searchPath, outputMode, headLimit) {
+  const { readdirSync, readFileSync, statSync } = fs;
+  const regex = new RegExp(input.pattern, input.case_insensitive ? "gi" : "g");
+  const globPattern = input.glob;
+  const results = [];
+  const filenames = new Set();
+
+  function walk(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (VCS_EXCLUDE_DIRS.includes(entry.name)) continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile()) {
+        if (globPattern && !matchGlob(entry.name, globPattern)) continue;
+        try {
+          const content = readFileSync(fullPath, "utf-8");
+          const lines = content.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            if (regex.test(lines[i])) {
+              filenames.add(fullPath);
+              results.push(`${fullPath}:${i + 1}:${lines[i].slice(0, MAX_LINE_LENGTH)}`);
+              if (headLimit > 0 && results.length >= headLimit) return;
+            }
+            regex.lastIndex = 0;
+          }
+        } catch { /* skip unreadable files */ }
+      }
+    }
+  }
+
+  walk(searchPath);
+
+  return {
+    mode: outputMode,
+    numFiles: filenames.size,
+    filenames: [...filenames],
+    content: outputMode === "content" ? results.join("\n") : "",
+    numMatches: results.length,
+    appliedLimit: headLimit,
+    fallback: true,
+  };
+}
+
+function matchGlob(filename, glob) {
+  // Simple extension glob matching (e.g., "*.tsx", "*.{ts,tsx}")
+  if (glob.startsWith("*.")) {
+    const exts = glob.slice(1).replace(/[{}]/g, "").split(",");
+    return exts.some((ext) => filename.endsWith(ext));
+  }
+  return true;
+}
+
+export class GrepError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GrepError";
+  }
+}

package/src/agents/shared-tools/index.js

@@ -0,0 +1,46 @@
+/**
+ * Shared Tools — Common tool implementations for all personas.
+ *
+ * Generic file/search/edit tools live here. Domain-specific tools
+ * (FrontendAnalyze, BackendAnalyze, DataAnalyze) stay in persona folders.
+ * Each persona's dispatch.js imports SHARED_TOOLS and merges with its own.
+ */
+
+import { fileRead } from "./file-read.js";
+import { grep } from "./grep.js";
+import { glob } from "./glob.js";
+import { shell } from "./shell.js";
+import { fileEdit } from "./file-edit.js";
+
+/**
+ * Tool map for generic tools shared across all personas.
+ * Merge with persona-specific tools in each persona's dispatch.js.
+ */
+export const SHARED_TOOLS = {
+  FileRead: fileRead,
+  Grep: grep,
+  Glob: glob,
+  Shell: shell,
+  FileEdit: fileEdit,
+};
+
+/**
+ * Read-only tool names (safe for concurrent execution in swarm sub-agents).
+ */
+export const SHARED_READ_ONLY_TOOLS = new Set(["FileRead", "Grep", "Glob"]);
+
+// Re-export individual tools for direct import
+export { fileRead, FileReadError } from "./file-read.js";
+export { grep, GrepError } from "./grep.js";
+export { glob, GlobError } from "./glob.js";
+export { shell, analyzeCommand, buildScrubbedEnv, ShellError, ShellBlockedError } from "./shell.js";
+export { fileEdit, FileEditError } from "./file-edit.js";
+export { PathGuardError, resolveGuardedPath } from "./path-guards.js";
+
+// Re-export dispatch infrastructure
+export {
+  createToolDispatcher,
+  createAgentContext,
+  ToolDispatchError,
+  BudgetExhaustedError,
+} from "./dispatch-core.js";

package/src/agents/shared-tools/path-guards.js

@@ -0,0 +1,161 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const POSIX_BLOCKED_PREFIXES = ["/dev", "/proc", "/sys"];
+const WINDOWS_DEVICE_SEGMENT = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const WINDOWS_DEVICE_NAMESPACE_PATTERN = /^\\\\[?.]\\.+/;
+const WINDOWS_UNC_PATTERN = /^\\\\(?![?.]\\)/;
+const POSIX_UNC_PATTERN = /^\/\/[^/]/;
+
+/**
+ * Resolve a user-provided file path and enforce sandbox-style guardrails.
+ * Returns the resolved path and realpath so callers can safely read/write.
+ */
+export function resolveGuardedPath({ filePath, allowedRoot }) {
+  const rawFilePath = normalizeInputPath(filePath);
+  assertPathNotNetwork(rawFilePath);
+  assertPathNotDeviceNamespace(rawFilePath);
+
+  const resolvedPath = path.resolve(rawFilePath);
+  const realPath = resolveRealPathOrFallback(resolvedPath);
+
+  assertPathNotNetwork(resolvedPath);
+  assertPathNotNetwork(realPath);
+  assertPathNotDeviceNamespace(resolvedPath);
+  assertPathNotDeviceNamespace(realPath);
+  assertPathNotBlockedPosixSystemPath(resolvedPath);
+  assertPathNotBlockedPosixSystemPath(realPath);
+  assertPathNotWindowsDeviceSegment(resolvedPath);
+  assertPathNotWindowsDeviceSegment(realPath);
+
+  if (allowedRoot !== undefined && allowedRoot !== null && String(allowedRoot).trim()) {
+    const resolvedAllowedRoot = path.resolve(String(allowedRoot));
+    const allowedRootRealPath = resolveRealPathOrFallback(resolvedAllowedRoot);
+    assertPathWithinAllowedRoot(resolvedPath, resolvedAllowedRoot);
+    assertPathWithinAllowedRoot(realPath, allowedRootRealPath);
+  }
+
+  return {
+    resolvedPath,
+    realPath,
+  };
+}
+
+function normalizeInputPath(filePath) {
+  if (!filePath || typeof filePath !== "string") {
+    throw new PathGuardError(
+      "PATH_INVALID",
+      "file_path is required and must be a non-empty string.",
+    );
+  }
+
+  const trimmed = filePath.trim();
+  if (!trimmed) {
+    throw new PathGuardError(
+      "PATH_INVALID",
+      "file_path is required and must be a non-empty string.",
+    );
+  }
+  return trimmed;
+}
+
+function resolveRealPathOrFallback(candidatePath) {
+  try {
+    if (typeof fs.realpathSync.native === "function") {
+      return fs.realpathSync.native(candidatePath);
+    }
+    return fs.realpathSync(candidatePath);
+  } catch {
+    return candidatePath;
+  }
+}
+
+function assertPathNotNetwork(candidatePath) {
+  const normalized = String(candidatePath || "");
+  if (WINDOWS_UNC_PATTERN.test(normalized) || POSIX_UNC_PATTERN.test(normalized)) {
+    throw new PathGuardError(
+      "PATH_UNC_BLOCKED",
+      `Network paths are not allowed: ${candidatePath}`,
+    );
+  }
+}
+
+function assertPathNotDeviceNamespace(candidatePath) {
+  const normalized = String(candidatePath || "");
+  if (WINDOWS_DEVICE_NAMESPACE_PATTERN.test(normalized)) {
+    throw new PathGuardError(
+      "PATH_DEVICE_NAMESPACE_BLOCKED",
+      `Device namespace paths are not allowed: ${candidatePath}`,
+    );
+  }
+}
+
+function assertPathNotBlockedPosixSystemPath(candidatePath) {
+  const normalized = String(candidatePath || "").replace(/\\/g, "/");
+  for (const prefix of POSIX_BLOCKED_PREFIXES) {
+    if (normalized === prefix || normalized.startsWith(`${prefix}/`)) {
+      throw new PathGuardError(
+        "PATH_SYSTEM_BLOCKED",
+        `Blocked system path: ${candidatePath}`,
+      );
+    }
+  }
+}
+
+function assertPathNotWindowsDeviceSegment(candidatePath) {
+  if (process.platform !== "win32") {
+    return;
+  }
+
+  const normalized = String(candidatePath || "").replace(/\//g, "\\");
+  const segments = normalized.split("\\").filter(Boolean);
+  for (const segment of segments) {
+    if (/^[a-z]:$/i.test(segment)) {
+      continue;
+    }
+    if (WINDOWS_DEVICE_SEGMENT.test(segment)) {
+      throw new PathGuardError(
+        "PATH_WINDOWS_DEVICE_BLOCKED",
+        `Blocked device path segment: ${candidatePath}`,
+      );
+    }
+  }
+}
+
+function assertPathWithinAllowedRoot(candidatePath, allowedRoot) {
+  if (isPathInsideRoot(candidatePath, allowedRoot)) {
+    return;
+  }
+  throw new PathGuardError(
+    "PATH_OUTSIDE_ALLOWED_ROOT",
+    `Path escapes allowed root: ${candidatePath} (root: ${allowedRoot})`,
+  );
+}
+
+function isPathInsideRoot(candidatePath, rootPath) {
+  const normalizedCandidate = normalizeForComparison(candidatePath);
+  const normalizedRoot = normalizeForComparison(rootPath);
+  const relative = path.relative(normalizedRoot, normalizedCandidate);
+
+  if (!relative) {
+    return true;
+  }
+
+  return !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+
+function normalizeForComparison(candidatePath) {
+  const resolved = path.resolve(candidatePath);
+  if (process.platform === "win32") {
+    return resolved.toLowerCase();
+  }
+  return resolved;
+}
+
+export class PathGuardError extends Error {
+  constructor(code, message) {
+    super(`[${code}] ${message}`);
+    this.name = "PathGuardError";
+    this.code = code;
+  }
+}