@theokit/sdk-tools 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.15.0
+
+### Minor Changes
+
+- 324835f: M15 — complete the surface-agnostic tool injection. `search_text`, `glob_files`, and `edit_file` now
+  accept an optional `filesystem` (`FilesystemProvider`), joining `shell_exec`/`git_diff` (`sandbox`) and
+  `interactive_shell`/`write_stdin` (`interactive`). When a backend is injected the recursive walk / read
+  / backup / write go through it in project-relative path space (so the tool runs unchanged on a local
+  disk, a cluster container, or a Tauri desktop); when omitted the local `fs` path is byte-identical to
+  before. Backward compatibility is proven by conformance tests that run each tool through the real
+  `LocalFilesystem`/`LocalSandbox` backends and assert identical output to the local path. Additive — no
+  breaking change.
+
 ## 0.11.1
 
 ### Patch Changes

package/dist/index.cjs

@@ -7,11 +7,12 @@ var zod = require('zod');
 var fs = require('fs');
 var pathSafety = require('@theokit/sdk/path-safety');
 var persistence = require('@theokit/sdk/persistence');
+var filesystem = require('@theokit/sdk/filesystem');
 var child_process = require('child_process');
+var sandbox = require('@theokit/sdk/sandbox');
 var interactive = require('@theokit/sdk/interactive');
 var promises$1 = require('dns/promises');
 var net = require('net');
-var filesystem = require('@theokit/sdk/filesystem');
 
 // src/apply-patch.ts
 var PathTraversalError = class extends sdk.ConfigurationError {
@@ -350,8 +351,79 @@ ${find}`);
 }
 
 // src/edit-file.ts
+function computeEdit(content, old_string, new_string) {
+  const exactIdx = content.indexOf(old_string);
+  if (exactIdx !== -1) {
+    return {
+      ok: true,
+      result: content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length)
+    };
+  }
+  const normalizedContent = normalizeWhitespace(content);
+  const normalizedOld = normalizeWhitespace(old_string);
+  const normalizedIdx = normalizedContent.indexOf(normalizedOld);
+  if (normalizedIdx !== -1) {
+    const span = findOriginalSpan(content, normalizedContent, normalizedIdx, normalizedOld.length);
+    return {
+      ok: true,
+      result: content.slice(0, span.start) + new_string + content.slice(span.end)
+    };
+  }
+  try {
+    return { ok: true, result: replaceUnique(content, old_string, new_string) };
+  } catch (err) {
+    if (err instanceof ContextMatchError) return { ok: false, error: "no_match" };
+    throw err;
+  }
+}
+async function editViaBackend(filesystem$1, ctx, path, old_string, new_string) {
+  const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
+  let content;
+  try {
+    content = await backend.readFile(path);
+  } catch {
+    return JSON.stringify({ ok: false, error: "not_found", path });
+  }
+  const outcome = computeEdit(content, old_string, new_string);
+  if (!outcome.ok) return JSON.stringify({ ok: false, error: "no_match", path });
+  await backend.writeFile(`${path}.bak`, content);
+  await backend.writeFile(path, outcome.result);
+  return JSON.stringify({ ok: true, replacements: 1 });
+}
+async function editViaLocal(projectRoot, path, old_string, new_string) {
+  const absolutePath = safePathJoin(projectRoot, path);
+  let content;
+  try {
+    content = await promises.readFile(absolutePath, "utf-8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT") {
+      return JSON.stringify({ ok: false, error: "not_found", path });
+    }
+    throw err;
+  }
+  const outcome = computeEdit(content, old_string, new_string);
+  if (!outcome.ok) return JSON.stringify({ ok: false, error: "no_match", path });
+  await promises.copyFile(absolutePath, `${absolutePath}.bak`);
+  await promises.writeFile(absolutePath, outcome.result, "utf-8");
+  return JSON.stringify({ ok: true, replacements: 1 });
+}
+function editScopeError(path, projectRoot) {
+  if (isForbiddenPath(path)) {
+    return JSON.stringify({ ok: false, error: "forbidden_path", path });
+  }
+  try {
+    assertNoSymlinkEscape(safePathJoin(projectRoot, path), projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
 function createEditFileTool(opts) {
-  const { projectRoot } = opts;
+  const { projectRoot, filesystem } = opts;
   return sdk.Tool.create({
     name: "edit_file",
     description: "Make an exact string replacement in a project-relative file. Replaces the FIRST occurrence of old_string with new_string (a whitespace-normalized fallback is attempted if the exact match fails) and writes a .bak backup first. Read the file first so old_string matches the on-disk text exactly; include enough surrounding context to make it unique \u2014 only the first match is replaced, so a too-short old_string can edit the wrong location. old_string must be non-empty and differ from new_string; to change every occurrence, call edit_file repeatedly. Returns { ok, replacements } or { ok: false, error }.",
@@ -360,67 +432,13 @@ function createEditFileTool(opts) {
       old_string: zod.z.string().min(1).describe("String to find in the file."),
       new_string: zod.z.string().describe("Replacement string.")
     }),
-    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: unified diff parsing is inherently complex
-    handler: async ({ path, old_string, new_string }) => {
+    handler: async ({ path, old_string, new_string }, ctx) => {
       if (old_string === new_string) {
         return JSON.stringify({ ok: false, error: "no_change", path });
       }
-      if (isForbiddenPath(path)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
-      }
-      let absolutePath;
-      try {
-        absolutePath = safePathJoin(projectRoot, path);
-        assertNoSymlinkEscape(absolutePath, projectRoot);
-      } catch (err) {
-        if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-          return JSON.stringify({ ok: false, error: "path_traversal", path });
-        }
-        throw err;
-      }
-      let content;
-      try {
-        content = await promises.readFile(absolutePath, "utf-8");
-      } catch (err) {
-        const e = err;
-        if (e.code === "ENOENT") {
-          return JSON.stringify({ ok: false, error: "not_found", path });
-        }
-        throw err;
-      }
-      const exactIdx = content.indexOf(old_string);
-      if (exactIdx !== -1) {
-        await promises.copyFile(absolutePath, `${absolutePath}.bak`);
-        const result = content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length);
-        await promises.writeFile(absolutePath, result, "utf-8");
-        return JSON.stringify({ ok: true, replacements: 1 });
-      }
-      const normalizedContent = normalizeWhitespace(content);
-      const normalizedOld = normalizeWhitespace(old_string);
-      const normalizedIdx = normalizedContent.indexOf(normalizedOld);
-      if (normalizedIdx !== -1) {
-        const span = findOriginalSpan(
-          content,
-          normalizedContent,
-          normalizedIdx,
-          normalizedOld.length
-        );
-        await promises.copyFile(absolutePath, `${absolutePath}.bak`);
-        const result = content.slice(0, span.start) + new_string + content.slice(span.end);
-        await promises.writeFile(absolutePath, result, "utf-8");
-        return JSON.stringify({ ok: true, replacements: 1 });
-      }
-      try {
-        const result = replaceUnique(content, old_string, new_string);
-        await promises.copyFile(absolutePath, `${absolutePath}.bak`);
-        await promises.writeFile(absolutePath, result, "utf-8");
-        return JSON.stringify({ ok: true, replacements: 1 });
-      } catch (err) {
-        if (err instanceof ContextMatchError) {
-          return JSON.stringify({ ok: false, error: "no_match", path });
-        }
-        throw err;
-      }
+      const scopeErr = editScopeError(path, projectRoot);
+      if (scopeErr !== null) return scopeErr;
+      return filesystem !== void 0 ? editViaBackend(filesystem, ctx, path, old_string, new_string) : editViaLocal(projectRoot, path, old_string, new_string);
     }
   });
 }
@@ -533,11 +551,27 @@ function attachChildSettlers(child, gate, onClose, onError, resolve2) {
 // src/git-diff.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_STDOUT_BYTES = 5 * 1024 * 1024;
+function shq(arg) {
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+async function diffViaSandbox(sandbox$1, ctx, cached, path, projectRoot, timeoutMs) {
+  const scopeCheck = checkPathScope(path, projectRoot);
+  if (scopeCheck !== null) return scopeCheck;
+  const command = ["git", ...buildDiffArgs(cached, path)].map(shq).join(" ");
+  const backend = await sandbox.resolveSandbox(sandbox$1, ctx ?? {});
+  const r = await backend.execute(command, { timeoutMs });
+  if (r.timedOut) return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
+  if (r.exitCode !== 0) {
+    return /not a git repository/i.test(r.stderr) ? JSON.stringify({ ok: false, error: "not_a_repo" }) : JSON.stringify({ ok: false, error: "git_failed", stderr: r.stderr });
+  }
+  return JSON.stringify({ ok: true, diff: r.stdout, truncated: false });
+}
 function createGitDiffTool(opts) {
   const {
     projectRoot,
     timeoutMs = DEFAULT_TIMEOUT_MS,
-    maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES
+    maxStdoutBytes = DEFAULT_MAX_STDOUT_BYTES,
+    sandbox
   } = opts;
   return sdk.Tool.create({
     name: "git_diff",
@@ -546,7 +580,10 @@ function createGitDiffTool(opts) {
       path: zod.z.string().optional().describe("Optional project-relative file or dir scope."),
       cached: zod.z.boolean().optional().describe("If true, show staged changes (git diff --cached). Default false.")
     }),
-    handler: async ({ path: path$1, cached }) => {
+    handler: async ({ path: path$1, cached }, ctx) => {
+      if (sandbox !== void 0) {
+        return diffViaSandbox(sandbox, ctx, cached, path$1, projectRoot, timeoutMs);
+      }
       if (!fs.existsSync(path.join(projectRoot, ".git"))) {
         return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
@@ -620,7 +657,7 @@ function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
 }
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
 function createGlobTool(opts) {
-  const { projectRoot } = opts;
+  const { projectRoot, filesystem: filesystem$1 } = opts;
   return sdk.Tool.create({
     name: "glob_files",
     description: "Find files by glob pattern across the project \u2014 fast at any repo size. Use glob_files when you know the filename SHAPE; use search_text when you know the file CONTENT; use read_file when you know the exact path. The pattern supports * and ** wildcards (e.g. '**/*.ts', 'src/**/*.json'); node_modules/.git/dist/.theo are excluded and results are relative paths. Returns { ok, files } or { ok: false, error }.",
@@ -628,20 +665,18 @@ function createGlobTool(opts) {
       pattern: zod.z.string().min(1).describe("Glob pattern (e.g. '**/*.ts', 'src/**/*.json')."),
       cwd: zod.z.string().optional().describe("Project-relative subdirectory to search from.")
     }),
-    handler: async ({ pattern, cwd }) => {
-      let searchRoot = projectRoot;
-      if (cwd) {
-        try {
-          searchRoot = safePathJoin(projectRoot, cwd);
-          assertNoSymlinkEscape(searchRoot, projectRoot);
-        } catch (err) {
-          if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-            return JSON.stringify({ ok: false, error: "path_traversal", path: cwd });
-          }
-          throw err;
-        }
-      }
+    handler: async ({ pattern, cwd }, ctx) => {
+      const scopeErr = globScopeError(cwd, projectRoot);
+      if (scopeErr !== null) return scopeErr;
       const regex = globToRegex(pattern);
+      if (filesystem$1 !== void 0) {
+        const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
+        const searchRel = cwd ?? "";
+        const found = [];
+        await walkDirBackend(backend, searchRel, searchRel, regex, found);
+        return JSON.stringify({ ok: true, files: found.sort(), count: found.length });
+      }
+      const searchRoot = cwd ? safePathJoin(projectRoot, cwd) : projectRoot;
       const files = [];
       await walkDir(searchRoot, searchRoot, regex, files);
       const relativePaths = files.map((f) => path.relative(projectRoot, f)).sort();
@@ -649,6 +684,18 @@ function createGlobTool(opts) {
     }
   });
 }
+function globScopeError(cwd, projectRoot) {
+  if (!cwd) return null;
+  try {
+    assertNoSymlinkEscape(safePathJoin(projectRoot, cwd), projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path: cwd });
+    }
+    throw err;
+  }
+}
 async function walkDir(base, dir, pattern, results) {
   let entries;
   try {
@@ -667,6 +714,33 @@ async function walkDir(base, dir, pattern, results) {
     }
   }
 }
+async function walkDirBackend(backend, base, dir, pattern, results) {
+  let names;
+  try {
+    names = await backend.list(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    await walkBackendEntry(backend, base, dir, name, pattern, results);
+  }
+}
+async function walkBackendEntry(backend, base, dir, name, pattern, results) {
+  if (DEFAULT_EXCLUDES.has(name)) return;
+  const fullRel = dir === "" ? name : `${dir}/${name}`;
+  const relPath = base === "" ? fullRel : path.relative(base, fullRel);
+  let st;
+  try {
+    st = await backend.stat(fullRel);
+  } catch {
+    return;
+  }
+  if (st.isDirectory) {
+    await walkDirBackend(backend, base, fullRel, pattern, results);
+  } else if (st.isFile && pattern.test(relPath)) {
+    results.push(fullRel);
+  }
+}
 function globToRegex(pattern) {
   let regexStr = "";
   let i = 0;
@@ -1738,7 +1812,8 @@ function createSearchTextTool(opts) {
   const {
     projectRoot,
     maxMatches = DEFAULT_MAX_MATCHES,
-    maxFileSize = DEFAULT_MAX_FILE_SIZE
+    maxFileSize = DEFAULT_MAX_FILE_SIZE,
+    filesystem: filesystem$1
   } = opts;
   return sdk.Tool.create({
     name: "search_text",
@@ -1747,9 +1822,7 @@ function createSearchTextTool(opts) {
       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.")
     }),
-    handler: async ({ query, path }) => {
-      const scope = resolveSearchScope(path, projectRoot);
-      if ("error" in scope) return scope.error;
+    handler: async ({ query, path }, ctx) => {
       const state = {
         matches: [],
         totalMatches: 0,
@@ -1759,6 +1832,20 @@ function createSearchTextTool(opts) {
         maxFileSize,
         projectRoot
       };
+      if (filesystem$1 !== void 0) {
+        const scopeRel = resolveScopeRel(path, projectRoot);
+        if ("error" in scopeRel) return scopeRel.error;
+        const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
+        await walkBackend(backend, scopeRel.rel, state);
+        return JSON.stringify({
+          ok: true,
+          matches: state.matches,
+          truncated: state.truncated,
+          totalMatches: state.totalMatches
+        });
+      }
+      const scope = resolveSearchScope(path, projectRoot);
+      if ("error" in scope) return scope.error;
       await walk(scope.scopeAbs, state);
       return JSON.stringify({
         ok: true,
@@ -1846,11 +1933,78 @@ async function scanFile(absPath, relPath, state) {
     if (!recordMatch(state, relPath, i + 1, line)) return;
   }
 }
+function resolveScopeRel(path, projectRoot) {
+  const scopeRel = path === void 0 || path === "" || path === "." ? "" : path;
+  if (scopeRel === "") return { rel: "" };
+  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 }) };
+    }
+    throw err;
+  }
+}
+async function walkBackend(backend, dirRel, state) {
+  if (state.truncated) return;
+  let names;
+  try {
+    names = await backend.list(dirRel);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (state.truncated) return;
+    await handleBackendEntry(backend, dirRel, name, state);
+  }
+}
+async function handleBackendEntry(backend, dirRel, name, state) {
+  const entryRel = dirRel === "" ? name : `${dirRel}/${name}`;
+  if (isForbiddenPath(entryRel)) return;
+  let st;
+  try {
+    st = await backend.stat(entryRel);
+  } catch {
+    return;
+  }
+  if (st.isDirectory) {
+    await walkBackend(backend, entryRel, state);
+  } else if (st.isFile) {
+    await scanFileBackend(backend, entryRel, st.size, state);
+  }
+}
+async function scanFileBackend(backend, relPath, size, state) {
+  if (size > state.maxFileSize) return;
+  let content;
+  try {
+    content = await backend.readFile(relPath);
+  } catch {
+    return;
+  }
+  if (content.slice(0, BINARY_PROBE_BYTES2).includes("\0")) return;
+  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 (!recordMatch(state, relPath, i + 1, line)) return;
+  }
+}
 var DEFAULT_TIMEOUT_MS3 = 3e4;
 var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+async function execViaSandbox(sandbox$1, ctx, command, timeoutMs) {
+  const backend = await sandbox.resolveSandbox(sandbox$1, ctx ?? {});
+  const r = await backend.execute(command, { timeoutMs });
+  return r.timedOut ? JSON.stringify({ ok: false, error: "timeout", timeout_ms: timeoutMs }) : JSON.stringify({ ok: true, stdout: r.stdout, stderr: r.stderr, exit_code: r.exitCode });
+}
 function createShellTool(opts) {
-  const { projectRoot, defaultTimeoutMs = DEFAULT_TIMEOUT_MS3, allowCatastrophic = false } = opts;
+  const {
+    projectRoot,
+    defaultTimeoutMs = DEFAULT_TIMEOUT_MS3,
+    allowCatastrophic = false,
+    sandbox
+  } = opts;
   return sdk.Tool.create({
     name: "shell_exec",
     description: "Execute a shell command in the project directory. Use this for terminal operations \u2014 running tests, git, package managers, build tools. Do NOT use it for file operations (reading, writing, editing, finding files): prefer the specialized read_file/write_file/edit_file/glob_files/search_text tools, which are path-checked and safer. Only commit, push, or change git state when the user explicitly asks. timeout_ms defaults to 30000 (max 300000); stdout/stderr are capped (~5 MB). Returns { ok, stdout, stderr, exit_code } or { ok: false, error }.",
@@ -1858,7 +2012,7 @@ function createShellTool(opts) {
       command: zod.z.string().min(1).describe("Shell command to execute."),
       timeout_ms: zod.z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
     }),
-    handler: async ({ command, timeout_ms }) => {
+    handler: async ({ command, timeout_ms }, ctx) => {
       if (!allowCatastrophic) {
         const reason = catastrophicShellReason(command);
         if (reason) {
@@ -1867,8 +2021,8 @@ function createShellTool(opts) {
         }
       }
       const timeoutMs = Math.min(timeout_ms ?? defaultTimeoutMs, MAX_TIMEOUT_MS);
-      const result = await runShell(projectRoot, command, timeoutMs);
-      return result;
+      if (sandbox !== void 0) return execViaSandbox(sandbox, ctx, command, timeoutMs);
+      return runShell(projectRoot, command, timeoutMs);
     }
   });
 }