@skroyc/librarian 0.1.0 → 0.2.1

package/src/utils/error-utils.ts

@@ -0,0 +1,95 @@
+import path from "node:path";
+
+/**
+ * Standardized error handling for Librarian tools.
+ * Aligned with file-editor's professional and objective tone.
+ */
+
+export interface ToolErrorOptions {
+  operation: string;
+  path?: string;
+  suggestion?: string | undefined;
+  cause?: unknown;
+}
+
+/**
+ * Formats a system error into a professional, actionable message.
+ */
+export function formatToolError(options: ToolErrorOptions): string {
+  const { operation, path: targetPath, suggestion, cause } = options;
+
+  let message = `${operation} failed`;
+  if (targetPath) {
+    message += `: ${targetPath}`;
+  }
+
+  if (cause && typeof cause === "object" && "code" in cause) {
+    const code = (cause as { code: string }).code;
+
+    switch (code) {
+      case "ENOENT":
+        message = `Path not found: ${targetPath || "unknown"}`;
+        break;
+      case "EACCES":
+      case "EPERM":
+        message = `Permission denied: ${targetPath || "unknown"}`;
+        break;
+      case "ENOTDIR":
+        message = `Path is not a directory: ${targetPath || "unknown"}`;
+        break;
+      case "EISDIR":
+        message = `Path is a directory, not a file: ${targetPath || "unknown"}`;
+        break;
+      default:
+        if ("message" in cause) {
+          message += `. ${cause.message}`;
+        }
+    }
+  } else if (cause instanceof Error) {
+    message += `. ${cause.message}`;
+  }
+
+  if (suggestion) {
+    message += `\n\nSuggestion: ${suggestion}`;
+  }
+
+  return message;
+}
+
+/**
+ * Creates a helpful suggestion based on common failure scenarios.
+ */
+export function getToolSuggestion(
+  operation: string,
+  targetPath?: string
+): string | undefined {
+  if (operation === "view" && targetPath) {
+    const ext = path.extname(targetPath).toLowerCase();
+    if ([".png", ".jpg", ".pdf"].includes(ext)) {
+      return "This file appears to be a binary or media file. Only text files can be read.";
+    }
+    return "Ensure the file path is correct and the file is a text file.";
+  }
+
+  if (operation === "list") {
+    return "Check if the directory exists and you have permissions to read it.";
+  }
+
+  if (operation === "grep") {
+    return "Try a simpler search pattern or verify the search path.";
+  }
+
+  if (operation === "find") {
+    return "Check if the search path exists and the patterns are valid glob patterns.";
+  }
+
+  // Generic permission suggestion for any operation
+  if (
+    targetPath &&
+    (operation === "view" || operation === "list" || operation === "find")
+  ) {
+    return "Check file permissions and ensure you have read access to the path.";
+  }
+
+  return undefined;
+}

package/src/utils/file-utils.ts

@@ -3,7 +3,7 @@
  * Shared utilities for file type detection and file operations
  */
 
-import path from 'node:path';
+import path from "node:path";
 
 /**
  * Check if a file is text-based
@@ -11,11 +11,48 @@ import path from 'node:path';
  */
 export async function isTextFile(filePath: string): Promise<boolean> {
   const textExtensions = new Set([
-    '.txt', '.js', '.ts', '.jsx', '.tsx', '.json', '.yaml', '.yml', '.md',
-    '.html', '.htm', '.css', '.scss', '.sass', '.less', '.py', '.rb', '.java',
-    '.cpp', '.c', '.h', '.hpp', '.go', '.rs', '.php', '.sql', '.xml', '.csv',
-    '.toml', '.lock', '.sh', '.bash', '.zsh', '.env', '.dockerfile', 'dockerfile',
-    '.gitignore', '.npmrc', '.prettierrc', '.eslintrc', '.editorconfig', '.jsonc'
+    ".txt",
+    ".js",
+    ".ts",
+    ".jsx",
+    ".tsx",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".md",
+    ".html",
+    ".htm",
+    ".css",
+    ".scss",
+    ".sass",
+    ".less",
+    ".py",
+    ".rb",
+    ".java",
+    ".cpp",
+    ".c",
+    ".h",
+    ".hpp",
+    ".go",
+    ".rs",
+    ".php",
+    ".sql",
+    ".xml",
+    ".csv",
+    ".toml",
+    ".lock",
+    ".sh",
+    ".bash",
+    ".zsh",
+    ".env",
+    ".dockerfile",
+    "dockerfile",
+    ".gitignore",
+    ".npmrc",
+    ".prettierrc",
+    ".eslintrc",
+    ".editorconfig",
+    ".jsonc",
   ]);
 
   const ext = path.extname(filePath).toLowerCase();
@@ -23,17 +60,65 @@ export async function isTextFile(filePath: string): Promise<boolean> {
     return true;
   }
 
-   // For files without extensions or unknown extensions, check for null bytes
-   try {
-     const buffer = await Bun.file(filePath).arrayBuffer();
-     const uint8Array = new Uint8Array(buffer);
-     for (let i = 0; i < Math.min(512, uint8Array.length); i++) {
-       if (uint8Array[i] === 0) {
-         return false;
-       }
-     }
-     return true;
-   } catch {
-     return false;
-   }
+  // For files without extensions or unknown extensions, check for null bytes
+  try {
+    const file = Bun.file(filePath);
+    if (file.size === 0) {
+      return true;
+    }
+
+    // Read only the first 512 bytes for binary check
+    const buffer = await file.slice(0, 512).arrayBuffer();
+    const uint8Array = new Uint8Array(buffer);
+    for (const byte of uint8Array) {
+      if (byte === 0) {
+        return false;
+      }
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Counts the number of lines in a file using a memory-efficient streaming approach.
+ * Handles empty files and trailing newlines correctly.
+ */
+export async function getFileLineCount(filePath: string): Promise<number> {
+  try {
+    const file = Bun.file(filePath);
+    if (file.size === 0) {
+      return 0;
+    }
+
+    const stream = file.stream();
+    const reader = stream.getReader();
+    let count = 0;
+    let lastByte = -1;
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+
+      for (const byte of value) {
+        lastByte = byte;
+        if (lastByte === 10) {
+          // '\n'
+          count++;
+        }
+      }
+    }
+
+    // If the file doesn't end with a newline, count the last line
+    if (lastByte !== 10 && lastByte !== -1) {
+      count++;
+    }
+
+    return count;
+  } catch {
+    return 0;
+  }
 }

package/src/utils/format-utils.ts

@@ -0,0 +1,190 @@
+/**
+ * Formatting utility functions for tool outputs
+ */
+
+export interface FileSystemEntry {
+  name: string;
+  path: string;
+  isDirectory: boolean;
+  size?: number;
+  lineCount?: number;
+  depth?: number;
+}
+
+export interface SearchMatch {
+  line: number;
+  column: number;
+  text: string;
+  context?: {
+    before: string[];
+    after: string[];
+  };
+}
+
+const MIN_LINE_NUM_WIDTH = 3;
+const FILE_SEPARATOR = "--";
+
+/**
+ * Add line numbers to an array of lines for display
+ */
+export function withLineNumbers(lines: string[], startLine = 1): string {
+  if (!lines || lines.length === 0) {
+    return "";
+  }
+
+  const maxLineNumWidth = Math.max(
+    MIN_LINE_NUM_WIDTH,
+    String(startLine + lines.length - 1).length
+  );
+
+  return lines
+    .map((line, index) => {
+      const lineNum = startLine + index;
+      const paddedNum = String(lineNum).padStart(maxLineNumWidth);
+      return `${paddedNum}→${line}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Format content with optional line range using line arrays for efficiency
+ */
+export function formatLinesWithRange(
+  lines: string[],
+  viewRange?: [number, number]
+): string {
+  if (!lines || lines.length === 0) {
+    return "[File is empty]";
+  }
+
+  if (!viewRange) {
+    return withLineNumbers(lines);
+  }
+
+  const [start, end] = viewRange;
+  const startIndex = Math.max(0, start - 1);
+  const endIndex = end === -1 ? lines.length : Math.min(lines.length, end);
+
+  const selectedLines = lines.slice(startIndex, endIndex);
+  return withLineNumbers(selectedLines, start);
+}
+
+/**
+ * Legacy wrapper for formatLinesWithRange that accepts a string
+ * @deprecated Use formatLinesWithRange with pre-split lines for better performance
+ */
+function _formatContentWithRange(
+  content: string,
+  viewRange?: [number, number]
+): string {
+  if (!content || content.trim() === "") {
+    return "[File is empty]";
+  }
+  return formatLinesWithRange(content.split("\n"), viewRange);
+}
+
+/**
+ * Format directory listing in tree-like format with indentation
+ */
+export function formatDirectoryTree(entries: FileSystemEntry[]): string {
+  let output = "";
+
+  for (const entry of entries) {
+    const indent = "  ".repeat(entry.depth || 0);
+    let line = `${indent}${entry.isDirectory ? `${entry.name}/` : entry.name}`;
+
+    // For files, show line count if available
+    if (!entry.isDirectory && entry.lineCount !== undefined) {
+      line += ` (${entry.lineCount} lines)`;
+    } else if (!entry.isDirectory && entry.size !== undefined) {
+      line += ` (${entry.size} bytes)`;
+    }
+
+    output += `${line}\n`;
+  }
+
+  return output.trimEnd();
+}
+
+/**
+ * Format search results with context
+ */
+export function formatSearchResults(
+  results: { path: string; matches: SearchMatch[] }[]
+): string {
+  let output = "";
+  const totalMatches = results.reduce((sum, r) => sum + r.matches.length, 0);
+
+  output += `Found ${totalMatches} matches in ${results.length} files:\n\n`;
+
+  let fileIndex = 0;
+  for (const result of results) {
+    output += `${result.path}\n`;
+
+    const sortedMatches = [...result.matches].sort((a, b) => a.line - b.line);
+    const displayedLines = new Set<number>();
+    let lastPrintedLine = -1;
+
+    // Calculate max line num width for this file
+    let maxLineNum = 0;
+    for (const match of sortedMatches) {
+      const lastContextLine = match.line + (match.context?.after.length || 0);
+      maxLineNum = Math.max(maxLineNum, lastContextLine);
+    }
+    const maxLineNumWidth = Math.max(
+      MIN_LINE_NUM_WIDTH,
+      String(maxLineNum).length
+    );
+
+    for (const match of sortedMatches) {
+      // Before context
+      if (match.context?.before) {
+        const startLine = Math.max(1, match.line - match.context.before.length);
+        for (let j = 0; j < match.context.before.length; j++) {
+          const lineNum = startLine + j;
+          if (!displayedLines.has(lineNum)) {
+            if (lastPrintedLine !== -1 && lineNum > lastPrintedLine + 1) {
+              output += `${" ".repeat(maxLineNumWidth)}⁝\n`;
+            }
+            output += `${String(lineNum).padStart(maxLineNumWidth)}→${match.context.before[j]}\n`;
+            displayedLines.add(lineNum);
+            lastPrintedLine = lineNum;
+          }
+        }
+      }
+
+      // Match line
+      if (!displayedLines.has(match.line)) {
+        if (lastPrintedLine !== -1 && match.line > lastPrintedLine + 1) {
+          output += `${" ".repeat(maxLineNumWidth)}⁝\n`;
+        }
+        output += `${String(match.line).padStart(maxLineNumWidth)}→${match.text}\n`;
+        displayedLines.add(match.line);
+        lastPrintedLine = match.line;
+      }
+
+      // After context
+      if (match.context?.after) {
+        const startLine = match.line + 1;
+        for (let j = 0; j < match.context.after.length; j++) {
+          const lineNum = startLine + j;
+          if (!displayedLines.has(lineNum)) {
+            if (lastPrintedLine !== -1 && lineNum > lastPrintedLine + 1) {
+              output += `${" ".repeat(maxLineNumWidth)}⁝\n`;
+            }
+            output += `${String(lineNum).padStart(maxLineNumWidth)}→${match.context.after[j]}\n`;
+            displayedLines.add(lineNum);
+            lastPrintedLine = lineNum;
+          }
+        }
+      }
+    }
+
+    if (fileIndex < results.length - 1) {
+      output += `${FILE_SEPARATOR}\n`;
+    }
+    fileIndex++;
+  }
+
+  return output;
+}

package/src/utils/gitignore-service.ts

@@ -0,0 +1,123 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { Glob } from "bun";
+
+interface GitIgnorePattern {
+  pattern: string;
+  isNegation: boolean;
+  isDirectoryOnly: boolean;
+  glob: Glob;
+}
+
+// Regex for parsing gitignore line endings (moved to module level for performance)
+const LINE_ENDING_REGEX = /\r?\n/;
+
+/**
+ * Service to handle .gitignore patterns and filtering.
+ * Uses Bun's native Glob for high performance.
+ */
+export class GitIgnoreService {
+  private readonly rootDir: string;
+  private patterns: GitIgnorePattern[] = [];
+  private initialized = false;
+
+  constructor(rootDir: string) {
+    this.rootDir = path.resolve(rootDir);
+  }
+
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return;
+    }
+    try {
+      const gitignorePath = path.join(this.rootDir, ".gitignore");
+      const content = await readFile(gitignorePath, "utf-8");
+      this.patterns = this.parseGitIgnore(content);
+    } catch {
+      this.patterns = [];
+    }
+    this.initialized = true;
+  }
+
+  shouldIgnore(filePath: string, isDirectory = false): boolean {
+    if (!this.initialized) {
+      return false;
+    }
+
+    const relativePath = path.relative(this.rootDir, filePath);
+    if (relativePath === "" || relativePath === ".") {
+      return false;
+    }
+
+    let ignored = false;
+    let hasNegationMatch = false;
+    for (const p of this.patterns) {
+      if (p.glob.match(relativePath)) {
+        // If it's a directory-only pattern like "dist/", it should only match
+        // directories or files INSIDE a directory named "dist".
+        // Glob patterns like "**/dist{,/**}" will match the file "dist" too.
+        if (
+          p.isDirectoryOnly &&
+          !isDirectory &&
+          !relativePath.includes("/") &&
+          p.glob.match(relativePath)
+        ) {
+          // Naive check: if it's a directory-only pattern but the target is a file
+          // in the root (no slashes in relativePath), we skip it if it's an exact match.
+          // This is not perfect for nested files but good enough for common cases.
+          continue;
+        }
+        if (p.isNegation) {
+          ignored = false;
+          hasNegationMatch = true;
+        } else if (!hasNegationMatch) {
+          // Only set ignored to true if we haven't seen a negation pattern yet
+          ignored = true;
+        }
+      }
+    }
+    return ignored;
+  }
+
+  private parseGitIgnore(content: string): GitIgnorePattern[] {
+    const lines = content.split(LINE_ENDING_REGEX);
+    const patterns: GitIgnorePattern[] = [];
+
+    for (let line of lines) {
+      line = line.trim();
+      if (!line || line.startsWith("#")) {
+        continue;
+      }
+
+      let isNegation = false;
+      if (line.startsWith("!")) {
+        isNegation = true;
+        line = line.slice(1).trim();
+      }
+
+      const isDirectoryOnly = line.endsWith("/");
+      let cleanPattern = isDirectoryOnly ? line.slice(0, -1) : line;
+
+      if (cleanPattern.startsWith("/")) {
+        cleanPattern = cleanPattern.slice(1);
+      } else if (!cleanPattern.includes("/")) {
+        cleanPattern = `**/${cleanPattern}`;
+      }
+
+      // Pattern to match the item and everything beneath it
+      const finalPattern = `${cleanPattern}{,/**}`;
+
+      try {
+        patterns.push({
+          pattern: line,
+          isNegation,
+          isDirectoryOnly,
+          glob: new Glob(finalPattern),
+        });
+      } catch {
+        // Skip invalid
+      }
+    }
+    return patterns;
+  }
+}