@wrongstack/tools 0.313.0 → 0.316.1

package/dist/chunk-JOHXDF3D.js

@@ -0,0 +1,295 @@
+import {
+  getIndexState,
+  searchCodebaseIndex
+} from "./chunk-HYX2TZ7O.js";
+import {
+  codebaseIndexDirOverride
+} from "./chunk-DA4KNE2H.js";
+import {
+  isBinaryBuffer,
+  safeResolveReal,
+  sha256hex
+} from "./chunk-D33S4RQG.js";
+
+// src/read.ts
+import * as fs from "node:fs/promises";
+import { FsError, ToolValidationError } from "@wrongstack/core/types";
+import { toErrorMessage } from "@wrongstack/core/utils";
+var ADVANCED_MODE_META_KEY = "tools.read.advancedMode";
+var MAX_BYTES = 5 * 1024 * 1024;
+var readTool = {
+  name: "read",
+  category: "Filesystem",
+  description: "Read the contents of a file with line numbers. This is the primary way to inspect source code, configuration, or any text file before making changes. Lines are returned 1-indexed in the form `N\u2192content` (line number, then a `\u2192` separator, then the raw line). The `N\u2192` prefix is display-only \u2014 always strip it before reusing the text, e.g. never include it in `edit.old_string`. When advanced mode is on or `includeSymbols` is set, the result also includes a `symbols` field listing codebase-index symbol names, kinds, and line numbers for the file (not file content).",
+  usageHint: "FOUNDATIONAL TOOL \u2014 call this before almost any edit operation.\n\nBest practices:\n- Always read a file before using `edit`, `replace`, or `write` on it (the system often requires it for safety).\n- Use `offset` + `limit` for very large files instead of reading everything at once.\n- Default limit is generous (2000 lines) but can be increased.\n- The output format is designed to be directly usable as context for `edit` operations.\n- Set `includeSymbols: true` to also receive the codebase-index symbol listing for the file.\n- Enable advanced mode (`ctx.meta['tools.read.advancedMode'] = true`) to auto-inject symbols on every read.",
+  selection: {
+    doNotUseWhen: "you need to search many files for matching content.",
+    useInstead: ["grep"]
+  },
+  permission: "auto",
+  mutating: false,
+  capabilities: ["fs.read"],
+  icon: "file",
+  maxOutputBytes: 262144,
+  timeoutMs: 5e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Path to the file (relative to project root or absolute within project)."
+      },
+      offset: {
+        type: "integer",
+        minimum: 1,
+        description: "1-based starting line number. Use together with `limit` for large files."
+      },
+      limit: {
+        type: "integer",
+        minimum: 0,
+        description: "Maximum number of lines to return (default 2000). Values above 5000 are clamped to 5000 \u2014 page with `offset` for more."
+      },
+      mode: {
+        type: "string",
+        enum: ["content", "summary"],
+        description: "Return full line-numbered content (default) or a compact file summary with imports/exports/symbols."
+      },
+      includeSymbols: {
+        type: "boolean",
+        description: "When true, include the codebase-index symbol list for this file as a structured `symbols` field in the result. Overrides the advanced-mode meta flag per-call."
+      }
+    },
+    required: ["path"]
+  },
+  async execute(input, ctx, execOpts) {
+    if (!input?.path) {
+      throw new ToolValidationError({
+        message: "read: path is required",
+        field: "path"
+      });
+    }
+    const absPath = await safeResolveReal(input.path, ctx);
+    const shouldIncludeSymbols = input.includeSymbols === true || input.includeSymbols !== false && ctx.meta[ADVANCED_MODE_META_KEY] === true;
+    let stat2;
+    try {
+      stat2 = await fs.stat(absPath);
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") {
+        throw new FsError({
+          message: `read: file not found "${input.path}"`,
+          code: "FS_READ_FAILED",
+          path: absPath,
+          context: { errno: "ENOENT" }
+        });
+      }
+      throw new FsError({
+        message: `read: failed to stat "${input.path}": ${toErrorMessage(err)}`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { errno: code },
+        cause: err
+      });
+    }
+    if (!stat2.isFile()) {
+      throw new FsError({
+        message: `read: "${input.path}" is not a regular file`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { reason: "not-a-regular-file" }
+      });
+    }
+    if (stat2.size > MAX_BYTES) {
+      throw new FsError({
+        message: `read: file too large (${stat2.size} bytes, limit ${MAX_BYTES})`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { size: stat2.size, limit: MAX_BYTES, reason: "too-large" }
+      });
+    }
+    const offset = Math.max(1, input.offset ?? 1);
+    const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
+    const prior = getReadRangeRecord(ctx, absPath);
+    const requestedEnd = prior ? Math.min(offset + limit - 1, prior.totalLines) : offset + limit - 1;
+    if (input.mode !== "summary" && limit > 0 && prior && coversRange(prior, stat2.mtimeMs, offset, requestedEnd)) {
+      ctx.recordRead(absPath, stat2.mtimeMs);
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: `[unchanged since previous read: "${input.path}" mtime=${Math.round(stat2.mtimeMs)}; requested lines ${offset}-${requestedEnd} were already shown. Use offset/limit for a new range if needed.]`,
+        total_lines: prior.totalLines,
+        encoding: "utf8",
+        truncated: requestedEnd < prior.totalLines,
+        cached: true,
+        note: mergeSymbolNote("Repeated read suppressed to save tokens.", symResult2?.note),
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {}
+      };
+    }
+    const buf = await fs.readFile(absPath);
+    if (isBinaryBuffer(buf)) {
+      throw new FsError({
+        message: `read: "${input.path}" appears to be binary`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { reason: "binary" }
+      });
+    }
+    const text = buf.toString("utf8");
+    const contentHash = sha256hex(text);
+    const allLines = text.split(/\r\n|\r|\n/);
+    const total = allLines.length;
+    if (input.mode === "summary") {
+      ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat2.mtimeMs, total, 1, Math.min(total, 200));
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: summarizeFile(input.path, stat2.size, allLines),
+        total_lines: total,
+        encoding: "utf8",
+        truncated: total > 200,
+        note: mergeSymbolNote(
+          "Summary mode returned compact structure instead of full file content.",
+          symResult2?.note
+        ),
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {}
+      };
+    }
+    if (limit === 0) {
+      ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat2.mtimeMs, total, 1, 0);
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: "",
+        total_lines: total,
+        encoding: "utf8",
+        truncated: total > 0,
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {},
+        ...symResult2?.note ? { note: symResult2.note } : {}
+      };
+    }
+    if (offset > total) {
+      ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat2.mtimeMs, total, total + 1, total + 1);
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: `[offset ${offset} is past end of file "${input.path}" \u2014 file has ${total} line(s). Do not retry this offset.]`,
+        total_lines: total,
+        encoding: "utf8",
+        truncated: false,
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {},
+        ...symResult2?.note ? { note: symResult2.note } : {}
+      };
+    }
+    const slice = allLines.slice(offset - 1, offset - 1 + limit);
+    const truncated = offset - 1 + slice.length < total;
+    const width = String(offset + slice.length - 1).length;
+    const numbered = slice.map((line, i) => `${String(offset + i).padStart(width, " ")}\u2192${line}`).join("\n");
+    ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+    rememberReadRange(ctx, absPath, stat2.mtimeMs, total, offset, offset + slice.length - 1);
+    const symResult = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+    return {
+      text: numbered,
+      total_lines: total,
+      encoding: "utf8",
+      truncated,
+      ...symResult?.symbols ? { symbols: symResult.symbols } : {},
+      ...symResult?.note ? { note: symResult.note } : {}
+    };
+  }
+};
+async function fetchSymbolsForFile(absPath, ctx, signal) {
+  try {
+    const state = getIndexState();
+    if (!state.ready) return {};
+    const { results, total } = await searchCodebaseIndex(
+      {
+        projectRoot: ctx.projectRoot,
+        indexDir: codebaseIndexDirOverride(ctx),
+        query: "",
+        file: absPath,
+        limit: 500
+      },
+      { signal }
+    );
+    if (results.length === 0) return {};
+    const sorted = results.map((r) => ({
+      name: r.name,
+      kind: r.kind,
+      line: r.line,
+      col: r.col,
+      signature: r.signature
+    })).sort((a, b) => a.line - b.line || a.col - b.col);
+    const result = { symbols: sorted };
+    if (total > results.length) {
+      result.note = `Symbol listing truncated to ${results.length} of ${total} entries.`;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+function mergeSymbolNote(note, symNote) {
+  if (!symNote) return note;
+  if (!note) return symNote;
+  return `${note} ${symNote}`;
+}
+var READ_RANGES_META_KEY = "tools.read.ranges.v1";
+function getReadRanges(ctx) {
+  const existing = ctx.meta[READ_RANGES_META_KEY];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+    return existing;
+  }
+  const next = {};
+  ctx.meta[READ_RANGES_META_KEY] = next;
+  return next;
+}
+function getReadRangeRecord(ctx, absPath) {
+  return getReadRanges(ctx)[absPath];
+}
+function rememberReadRange(ctx, absPath, mtimeMs, totalLines, start, end) {
+  if (end < start) return;
+  const ranges = getReadRanges(ctx);
+  const prior = ranges[absPath];
+  const nextRanges = prior && Math.abs(prior.mtimeMs - mtimeMs) <= 1 ? prior.ranges.slice() : [];
+  nextRanges.push({ start, end });
+  ranges[absPath] = {
+    mtimeMs,
+    totalLines,
+    ranges: mergeRanges(nextRanges)
+  };
+}
+function coversRange(record, mtimeMs, start, end) {
+  if (Math.abs(record.mtimeMs - mtimeMs) > 1) return false;
+  return record.ranges.some((range) => range.start <= start && range.end >= end);
+}
+function mergeRanges(ranges) {
+  const sorted = ranges.slice().sort((a, b) => a.start - b.start);
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    if (!last || range.start > last.end + 1) {
+      merged.push({ ...range });
+      continue;
+    }
+    last.end = Math.max(last.end, range.end);
+  }
+  return merged;
+}
+function summarizeFile(filePath, bytes, lines) {
+  const interesting = lines.map((line, index) => ({ line: line.trim(), number: index + 1 })).filter(
+    ({ line }) => /^(import\s|export\s|class\s|interface\s|type\s|function\s|const\s+\w+\s*=|let\s+\w+\s*=|var\s+\w+\s*=|def\s+|async\s+function\s)/.test(
+      line
+    )
+  ).slice(0, 80).map(({ line, number }) => `${number}: ${line}`);
+  return [
+    `summary: ${filePath}`,
+    `bytes=${bytes}`,
+    `total_lines=${lines.length}`,
+    interesting.length > 0 ? `symbols/imports:
+${interesting.join("\n")}` : "symbols/imports: (none detected)"
+  ].join("\n");
+}
+
+export {
+  readTool
+};
+//# sourceMappingURL=chunk-JOHXDF3D.js.map