@theokit/sdk-tools 0.21.0 → 0.22.1

package/dist/index.js

@@ -5,9 +5,9 @@ import { z } from 'zod';
 import { safePathJoin, assertNoSymlinkEscape, PathTraversalError, ForbiddenPathError, isForbiddenPath, safeFilenameForId } from '@theokit/sdk/path-safety';
 import { replaceFileAtomic } from '@theokit/sdk/persistence';
 import { resolveFilesystem, FileNotFoundError, FilesystemSecurityError, FilesystemReadOnlyError, StaleFileError, FilesystemError } from '@theokit/sdk/filesystem';
-import { spawn } from 'child_process';
 import { existsSync, statSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'fs';
 import { resolveSandbox } from '@theokit/sdk/sandbox';
+import { spawn } from 'child_process';
 import { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
@@ -609,8 +609,8 @@ function editScopeError(path, projectRoot) {
 function createEditFileTool(opts) {
   const { projectRoot, filesystem } = opts;
   return 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 }.",
+    name: opts.name ?? "edit_file",
+    description: opts.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 }.",
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative file path."),
       old_string: z.string().min(1).describe("String to find in the file."),
@@ -682,21 +682,6 @@ function formatError(message, code) {
   return `> **Error:** ${prefix}${message}`;
 }
 
-// src/path-scope.ts
-function checkPathScope(path, projectRoot) {
-  if (path === void 0 || path === "") return null;
-  try {
-    const abs = safePathJoin(projectRoot, path);
-    assertNoSymlinkEscape(abs, projectRoot);
-    return null;
-  } catch (err) {
-    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-      return JSON.stringify({ ok: false, error: "path_traversal", path });
-    }
-    throw err;
-  }
-}
-
 // src/subprocess.ts
 function createSettleGate(timer) {
   let done = false;
@@ -732,6 +717,85 @@ function attachChildSettlers(child, gate, onClose, onError, resolve) {
   });
 }
 
+// src/internal/git-exec.ts
+function formatGitResult(result, timeoutMs) {
+  if (result.kind === "timeout") {
+    return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
+  }
+  if (result.kind === "error") {
+    return JSON.stringify({ ok: false, error: "git_failed", stderr: result.stderr });
+  }
+  return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
+}
+function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let stdoutBytes = 0;
+    let truncated = false;
+    const gate = armTimeoutKill(
+      child,
+      timeoutMs,
+      () => ({ kind: "timeout" }),
+      resolve
+    );
+    child.stdout.on("data", (chunk) => {
+      if (gate.settled()) return;
+      if (stdoutBytes >= maxStdoutBytes) {
+        truncated = true;
+        return;
+      }
+      const remaining = maxStdoutBytes - stdoutBytes;
+      if (chunk.length > remaining) {
+        stdoutChunks.push(chunk.subarray(0, remaining));
+        stdoutBytes = maxStdoutBytes;
+        truncated = true;
+      } else {
+        stdoutChunks.push(chunk);
+        stdoutBytes += chunk.length;
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderrChunks.push(chunk);
+    });
+    attachChildSettlers(
+      child,
+      gate,
+      (code) => {
+        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
+        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
+        return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
+      },
+      (err) => ({ kind: "error", stderr: err.message }),
+      resolve
+    );
+  });
+}
+
+// src/path-scope.ts
+function checkPathScope(path, projectRoot) {
+  if (path === void 0 || path === "") return null;
+  try {
+    const abs = safePathJoin(projectRoot, path);
+    assertNoSymlinkEscape(abs, projectRoot);
+    return null;
+  } catch (err) {
+    if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
+      return JSON.stringify({ ok: false, error: "path_traversal", path });
+    }
+    throw err;
+  }
+}
+var SEGMENTOS_SENSIVEIS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function ehProibidoEmQualquerProfundidade(path) {
+  const segs = path.replace(/\\/g, "/").split("/").filter(Boolean);
+  return segs.some((s) => {
+    if (s === ".env.example") return false;
+    return SEGMENTOS_SENSIVEIS.has(s) || /^\.env\./.test(s);
+  });
+}
+
 // src/git-diff.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEFAULT_MAX_STDOUT_BYTES = 5 * 1024 * 1024;
@@ -785,58 +849,25 @@ function buildDiffArgs(cached, path) {
   if (path !== void 0 && path !== "") args.push("--", path);
   return args;
 }
-function formatGitResult(result, timeoutMs) {
-  if (result.kind === "timeout") {
-    return JSON.stringify({ ok: false, error: "timeout", timeoutMs });
-  }
-  if (result.kind === "error") {
-    return JSON.stringify({ ok: false, error: "git_failed", stderr: result.stderr });
-  }
-  return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
-}
-function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
-  return new Promise((resolve) => {
-    const child = spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
-    const stdoutChunks = [];
-    const stderrChunks = [];
-    let stdoutBytes = 0;
-    let truncated = false;
-    const gate = armTimeoutKill(
-      child,
-      timeoutMs,
-      () => ({ kind: "timeout" }),
-      resolve
-    );
-    child.stdout.on("data", (chunk) => {
-      if (gate.settled()) return;
-      if (stdoutBytes >= maxStdoutBytes) {
-        truncated = true;
-        return;
-      }
-      const remaining = maxStdoutBytes - stdoutBytes;
-      if (chunk.length > remaining) {
-        stdoutChunks.push(chunk.subarray(0, remaining));
-        stdoutBytes = maxStdoutBytes;
-        truncated = true;
-      } else {
-        stdoutChunks.push(chunk);
-        stdoutBytes += chunk.length;
+function createGitStatusTool(opts) {
+  const { projectRoot, timeoutMs = 3e4, maxStdoutBytes = 5 * 1024 * 1024 } = opts;
+  return Tool.create({
+    name: opts.name ?? "git_status",
+    description: opts.description ?? "Show the working-tree status in porcelain format: staged, unstaged and untracked paths, one per line with a two-character status code. Use before committing, or to see what changed without reading the full diff. Optional 'path' scopes the report to a subdirectory.",
+    inputSchema: z.object({
+      path: z.string().optional().describe("Optional project-relative path to scope the status report.")
+    }),
+    handler: async ({ path }) => {
+      if (!existsSync(join(projectRoot, ".git"))) {
+        return JSON.stringify({ ok: false, error: "not_a_repo" });
       }
-    });
-    child.stderr.on("data", (chunk) => {
-      stderrChunks.push(chunk);
-    });
-    attachChildSettlers(
-      child,
-      gate,
-      (code) => {
-        const stdout = Buffer.concat(stdoutChunks).toString("utf-8");
-        const stderr = Buffer.concat(stderrChunks).toString("utf-8");
-        return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
-      },
-      (err) => ({ kind: "error", stderr: err.message }),
-      resolve
-    );
+      const scopeCheck = checkPathScope(path, projectRoot);
+      if (scopeCheck !== null) return scopeCheck;
+      const args = ["status", "--porcelain"];
+      if (path !== void 0 && path !== "") args.push("--", path);
+      const result = await runGitProcess(projectRoot, args, timeoutMs, maxStdoutBytes);
+      return formatGitResult(result, timeoutMs);
+    }
   });
 }
 var DEFAULT_EXCLUDES = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", ".theo"]);
@@ -1508,15 +1539,17 @@ var DEFAULT_MAX_ENTRIES = 500;
 function createListDirTool(opts) {
   const { projectRoot, max = DEFAULT_MAX_ENTRIES, filesystem } = opts;
   return Tool.create({
-    name: "list_dir",
-    description: `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
+    name: opts.name ?? "list_dir",
+    description: opts.description ?? `Return the direct entries of a project-relative directory. Refuses paths outside the project root or in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files). Caps at ${String(max)} entries by default; result carries truncated + totalCount.`,
     inputSchema: z.object({
       path: z.string().min(1).describe("Project-relative directory path. Use '.' for root.")
     }),
     handler: async ({ path }, ctx) => {
       const relative3 = path === "" || path === "." ? "." : path;
-      if (relative3 !== "." && isForbiddenPath(relative3)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
+      const veredito = decidirEscopo(relative3, path, opts.allowAbsolute === true);
+      if (veredito.erro !== void 0) return veredito.erro;
+      if (veredito.raizAbsoluta !== void 0) {
+        return listViaLocalFs(veredito.raizAbsoluta, ".", path, max);
       }
       if (filesystem) {
         const backend = await resolveFilesystem(filesystem, ctx ?? {});
@@ -1526,6 +1559,16 @@ function createListDirTool(opts) {
     }
   });
 }
+function decidirEscopo(relative3, original, allowAbsolute) {
+  const recusa = (error) => ({
+    erro: JSON.stringify({ ok: false, error, path: original })
+  });
+  if (relative3 !== "." && isForbiddenPath(relative3)) return recusa("forbidden_path");
+  if (!isAbsolute(relative3)) return {};
+  if (!allowAbsolute) return recusa("path_traversal");
+  if (ehProibidoEmQualquerProfundidade(relative3)) return recusa("forbidden_path");
+  return { raizAbsoluta: relative3 };
+}
 async function listViaLocalFs(projectRoot, relative3, originalPath, max) {
   const boundary = resolveDirBoundary(relative3, projectRoot, originalPath);
   if ("error" in boundary) return boundary.error;
@@ -1686,6 +1729,11 @@ function createPlanModeTool(options) {
 }
 
 // src/question.ts
+function askerDoContexto(context) {
+  if (typeof context !== "object" || context === null) return void 0;
+  const candidato = context.askUser;
+  return typeof candidato === "function" ? candidato : void 0;
+}
 function createQuestionTool(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e5;
   return {
@@ -1698,12 +1746,20 @@ function createQuestionTool(opts) {
       },
       required: ["question"]
     },
-    handler: async (input) => {
+    handler: async (input, ctx) => {
+      const askUser = askerDoContexto(ctx?.context) ?? opts.askUser;
+      if (askUser === void 0) {
+        return JSON.stringify({
+          ok: false,
+          error: "no_asker",
+          message: "No asker available: pass `askUser` to createQuestionTool, or provide `context.askUser` via SendOptions.context."
+        });
+      }
       const timeout = new Promise((_, reject) => {
         setTimeout(() => reject(new Error("timeout")), timeoutMs);
       });
       try {
-        const answer = await Promise.race([opts.askUser(input.question), timeout]);
+        const answer = await Promise.race([askUser(String(input.question ?? "")), timeout]);
         return JSON.stringify({ ok: true, answer });
       } catch (err) {
         if (err instanceof Error && err.message === "timeout") {
@@ -2041,8 +2097,8 @@ function createSearchTextTool(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 Tool.create({
-    name: "search_text",
-    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 }.`,
+    name: opts.name ?? "search_text",
+    description: opts.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: z.object({
       query: regex ? z.string().min(1).describe("A JavaScript regular expression, e.g. 'function\\\\s+main'.") : z.string().min(1).describe("Literal text to search for. Case-sensitive."),
       path: z.string().optional().describe(
@@ -2250,8 +2306,8 @@ function createShellTool(opts) {
     sandbox
   } = opts;
   return 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 }.",
+    name: opts.name ?? "shell_exec",
+    description: opts.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 }.",
     inputSchema: z.object({
       command: z.string().min(1).describe("Shell command to execute."),
       timeout_ms: z.number().int().positive().optional().describe("Timeout in milliseconds (default 30000, max 300000).")
@@ -2817,6 +2873,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGitStatusTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map