@theokit/sdk-tools 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.19.0
+
+### Minor Changes
+
+- `createSearchTextTool` gains two ADDITIVE, opt-in options (both default OFF ⇒ existing literal, project-
+  scoped behavior unchanged): `regex` — match `query` as a JavaScript RegExp (grep semantics; an invalid
+  pattern returns `{ ok: false, error: 'invalid_regex' }` before walking), and `allowAbsolute` — honor an
+  absolute `path` scope outside `projectRoot` (Codex read-only "reads-anywhere"; forbidden dirs still
+  skipped). Together they let one built-in cover both literal content search and grep-style regex search.
+
 ## 0.18.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1893,27 +1893,36 @@ function createSearchTextTool(opts) {
     projectRoot,
     maxMatches = DEFAULT_MAX_MATCHES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
-    filesystem: filesystem$1
+    filesystem: filesystem$1,
+    regex = false,
+    allowAbsolute = false
   } = opts;
+  const queryKind = regex ? "a JavaScript REGULAR EXPRESSION" : "LITERAL, CASE-SENSITIVE text";
+  const queryMatch = regex ? "matched as a regex" : "matched as a substring, not a regex";
   return sdk.Tool.create({
     name: "search_text",
-    description: `Search file CONTENTS for a LITERAL, CASE-SENSITIVE query across the project tree (the query is matched as a substring, not a regex). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
+    description: `Search file CONTENTS for ${queryKind} across the project tree (the query is ${queryMatch}). Use search_text when you know the content; use glob_files when you know the filename shape; use read_file when you know the exact path. Skips sensitive dirs (.env/.git/node_modules/.theo), binary files, and files over 1 MB; 'path' scopes the search to a subdirectory. Returns up to ${String(maxMatches)} matches as { file, line, preview } \u2014 cite locations to the user as file:line. Returns { ok, matches } or { ok: false, error }.`,
     inputSchema: zod.z.object({
-      query: zod.z.string().min(1).describe("Literal text to search for. Case-sensitive."),
-      path: zod.z.string().optional().describe("Optional project-relative directory to scope the search.")
+      query: regex ? zod.z.string().min(1).describe("A JavaScript regular expression, e.g. 'function\\\\s+main'.") : zod.z.string().min(1).describe("Literal text to search for. Case-sensitive."),
+      path: zod.z.string().optional().describe(
+        "Optional directory to scope the search (project-relative; absolute when allowed)."
+      )
     }),
     handler: async ({ query, path }, ctx) => {
+      const built = buildMatcher(query, regex);
+      if ("error" in built) return built.error;
+      const matcher = built.matcher;
       const state = {
         matches: [],
         totalMatches: 0,
         truncated: false,
-        query,
+        matcher,
         maxMatches,
         maxFileSize,
         projectRoot
       };
       if (filesystem$1 !== void 0) {
-        const scopeRel = resolveScopeRel(path, projectRoot);
+        const scopeRel = resolveScopeRel(path, projectRoot, allowAbsolute);
         if ("error" in scopeRel) return scopeRel.error;
         const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
         await walkBackend(backend, scopeRel.rel, state, 0);
@@ -1924,7 +1933,7 @@ function createSearchTextTool(opts) {
           totalMatches: state.totalMatches
         });
       }
-      const scope = resolveSearchScope(path, projectRoot);
+      const scope = resolveSearchScope(path, projectRoot, allowAbsolute);
       if ("error" in scope) return scope.error;
       await walk(scope.scopeAbs, state);
       return JSON.stringify({
@@ -1936,15 +1945,27 @@ function createSearchTextTool(opts) {
     }
   });
 }
-function resolveSearchScope(path, projectRoot) {
-  const scopeRel = path === void 0 || path === "" || path === "." ? "." : path;
+function buildMatcher(query, regex) {
+  if (!regex) return { matcher: (line) => line.includes(query) };
+  try {
+    const re = new RegExp(query);
+    return { matcher: (line) => re.test(line) };
+  } catch {
+    return { error: JSON.stringify({ ok: false, error: "invalid_regex", query }) };
+  }
+}
+function resolveSearchScope(path$1, projectRoot, allowAbsolute) {
+  const scopeRel = path$1 === void 0 || path$1 === "" || path$1 === "." ? "." : path$1;
+  if (allowAbsolute && path.isAbsolute(scopeRel)) {
+    return { scopeAbs: scopeRel };
+  }
   try {
     const scopeAbs = scopeRel === "." ? projectRoot : safePathJoin(projectRoot, scopeRel);
     assertNoSymlinkEscape(scopeAbs, projectRoot);
     return { scopeAbs };
   } catch (err) {
     if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-      return { error: JSON.stringify({ ok: false, error: "path_traversal", path }) };
+      return { error: JSON.stringify({ ok: false, error: "path_traversal", path: path$1 }) };
     }
     throw err;
   }
@@ -2009,19 +2030,20 @@ async function scanFile(absPath, relPath, state) {
   const lines = buffer.toString("utf-8").split("\n");
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
-    if (!line.includes(state.query)) continue;
+    if (!state.matcher(line)) continue;
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }
-function resolveScopeRel(path, projectRoot) {
-  const scopeRel = path === void 0 || path === "" || path === "." ? "" : path;
+function resolveScopeRel(path$1, projectRoot, allowAbsolute) {
+  const scopeRel = path$1 === void 0 || path$1 === "" || path$1 === "." ? "" : path$1;
   if (scopeRel === "") return { rel: "" };
+  if (allowAbsolute && path.isAbsolute(scopeRel)) return { rel: scopeRel };
   try {
     assertNoSymlinkEscape(safePathJoin(projectRoot, scopeRel), projectRoot);
     return { rel: scopeRel };
   } catch (err) {
     if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-      return { error: JSON.stringify({ ok: false, error: "path_traversal", path }) };
+      return { error: JSON.stringify({ ok: false, error: "path_traversal", path: path$1 }) };
     }
     throw err;
   }
@@ -2067,7 +2089,7 @@ async function scanFileBackend(backend, relPath, size, state) {
   const lines = content.split("\n");
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i];
-    if (!line.includes(state.query)) continue;
+    if (!state.matcher(line)) continue;
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }