@theokit/sdk-tools 0.20.0 → 0.21.0

package/dist/index.d.cts

@@ -14,9 +14,15 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
  * security-checked) before ANY write. A parse error, context mismatch, or path violation anywhere ⇒ typed
  * error and ZERO writes (stronger than Codex, which writes file-by-file and can leave partial writes).
  *
- * Return shape (always a JSON string):
+ * Return shape (always a JSON string — never throws on a bad patch):
  *   - `{ ok: true, files_patched: string[] }`
- *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' | 'patch_failed' }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' |
+ *        'patch_failed' | 'duplicate_target' | 'file_exists' | 'io_error' }`
+ *
+ * Security/robustness (M18 review): forbidden secrets (`.env`/`.git`/`node_modules`/`.theo`) are blocked
+ * at ANY path depth and against absolute-path spelling; a file touched by two hunks is rejected
+ * (`duplicate_target`); Add over an existing file is rejected (`file_exists`); Delete of a missing file
+ * is `not_found`; any unexpected fs error maps to `io_error` (the handler never throws).
  */
 
 interface CreateApplyPatchToolOptions {

package/dist/index.d.ts

@@ -14,9 +14,15 @@ import { InteractiveProvider } from '@theokit/sdk/interactive';
  * security-checked) before ANY write. A parse error, context mismatch, or path violation anywhere ⇒ typed
  * error and ZERO writes (stronger than Codex, which writes file-by-file and can leave partial writes).
  *
- * Return shape (always a JSON string):
+ * Return shape (always a JSON string — never throws on a bad patch):
  *   - `{ ok: true, files_patched: string[] }`
- *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' | 'patch_failed' }`
+ *   - `{ ok: false, error: 'parse_error' | 'path_traversal' | 'forbidden_path' | 'not_found' |
+ *        'patch_failed' | 'duplicate_target' | 'file_exists' | 'io_error' }`
+ *
+ * Security/robustness (M18 review): forbidden secrets (`.env`/`.git`/`node_modules`/`.theo`) are blocked
+ * at ANY path depth and against absolute-path spelling; a file touched by two hunks is rejected
+ * (`duplicate_target`); Add over an existing file is rejected (`file_exists`); Delete of a missing file
+ * is `not_found`; any unexpected fs error maps to `io_error` (the handler never throws).
  */
 
 interface CreateApplyPatchToolOptions {

package/dist/index.js

@@ -1,106 +1,18 @@
 import { rm, mkdir, writeFile, readFile, readdir, open, stat, copyFile } from 'fs/promises';
-import { dirname, join, relative, isAbsolute, resolve, sep } from 'path';
+import { dirname, relative, join, isAbsolute } from 'path';
 import { Tool, ConfigurationError } from '@theokit/sdk';
 import { z } from 'zod';
-import { existsSync, statSync, mkdirSync, writeFileSync, realpathSync, readFileSync, lstatSync, readlinkSync, readdirSync } from 'fs';
-import { safeFilenameForId, safePathJoin as safePathJoin$1 } from '@theokit/sdk/path-safety';
+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 { resolveInteractive, InteractiveUnavailableError, NoSuchSessionError } from '@theokit/sdk/interactive';
 import { lookup } from 'dns/promises';
 import { isIP } from 'net';
 
 // src/apply-patch.ts
-var PathTraversalError = class extends ConfigurationError {
-  name = "PathTraversalError";
-  constructor(input, resolvedPath) {
-    super(`Path traversal attempt: ${input} \u2192 ${resolvedPath}`, {
-      code: "path_traversal"
-    });
-  }
-};
-var ForbiddenPathError = class extends ConfigurationError {
-  name = "ForbiddenPathError";
-  constructor(path) {
-    super(
-      `Path '${path}' is in the sensitive-file blocklist (.env, .git/, node_modules/, .theo/, lock files)`,
-      {
-        code: "forbidden_path"
-      }
-    );
-  }
-};
-function safePathJoin(base, ...parts) {
-  if (base === "") {
-    throw new Error("safePathJoin: base must be non-empty");
-  }
-  const baseResolved = resolve(base);
-  const target = resolve(base, ...parts);
-  if (target !== baseResolved && !target.startsWith(baseResolved + sep)) {
-    throw new PathTraversalError(parts.join("/"), target);
-  }
-  return target;
-}
-function assertNoSymlinkEscape(path, base) {
-  let baseResolved;
-  try {
-    baseResolved = realpathSync(base);
-  } catch {
-    baseResolved = resolve(base);
-  }
-  const resolved = realpathOfDeepestExisting(path);
-  if (resolved === void 0) return;
-  if (resolved !== baseResolved && !resolved.startsWith(baseResolved + sep)) {
-    throw new PathTraversalError(`symlink ${path}`, resolved);
-  }
-}
-function realpathOfDeepestExisting(path) {
-  try {
-    return realpathSync(path);
-  } catch {
-  }
-  try {
-    const stat2 = lstatSync(path);
-    if (stat2.isSymbolicLink()) {
-      const target = readlinkSync(path);
-      const parentReal = realpathOfDeepestExisting(dirname(path));
-      const parentBase = parentReal ?? dirname(path);
-      return resolve(parentBase, target);
-    }
-  } catch {
-  }
-  let cursor = dirname(path);
-  let suffix = path.slice(cursor.length);
-  while (cursor !== dirname(cursor)) {
-    try {
-      const real = realpathSync(cursor);
-      return resolve(real, `.${suffix}`);
-    } catch {
-      suffix = path.slice(dirname(cursor).length);
-      cursor = dirname(cursor);
-    }
-  }
-  return void 0;
-}
-var LOCK_FILES = /* @__PURE__ */ new Set(["pnpm-lock.yaml", "package-lock.json", "yarn.lock", "bun.lockb"]);
-function isForbiddenPath(input) {
-  const normalized = input.replace(/\\/g, "/").replace(/^\.\//, "");
-  if (normalized.length === 0) return false;
-  const segments = normalized.split("/").filter((s) => s.length > 0);
-  if (segments.length === 0) return false;
-  const first = segments[0];
-  if (first === ".env.example") return false;
-  if (first === ".env") return true;
-  if (/^\.env\./.test(first)) return true;
-  if (first === ".git") return true;
-  if (first === "node_modules") return true;
-  if (first === ".theo") return true;
-  const basename = segments[segments.length - 1];
-  if (LOCK_FILES.has(basename)) return true;
-  return false;
-}
 
 // src/internal/v4a-patch.ts
 var BEGIN = "*** Begin Patch";
@@ -265,7 +177,14 @@ function matchesAt(lines, pattern, at, eq) {
 function seekSequence(lines, pattern, searchStart, eof) {
   if (pattern.length === 0) return searchStart;
   if (pattern.length > lines.length) return null;
-  const start = eof ? Math.max(searchStart, lines.length - pattern.length) : searchStart;
+  const starts = eof ? [Math.max(searchStart, lines.length - pattern.length), searchStart] : [searchStart];
+  for (const start of starts) {
+    const hit = searchFrom(lines, pattern, start);
+    if (hit !== null) return hit;
+  }
+  return null;
+}
+function searchFrom(lines, pattern, start) {
   for (const eq of LADDER) {
     for (let i = start; i <= lines.length - pattern.length; i++) {
       if (matchesAt(lines, pattern, i, eq)) return i;
@@ -322,12 +241,28 @@ async function applyV4APatch(projectRoot, patch) {
     const detail = err instanceof V4APatchError ? err.message : String(err);
     return JSON.stringify({ ok: false, error: "parse_error", detail });
   }
-  const plan = await buildPlan(projectRoot, hunks);
-  if ("error" in plan) return plan.error;
-  await executePlan(plan.ops);
-  return JSON.stringify({ ok: true, files_patched: plan.patched });
+  try {
+    const plan = await buildPlan(projectRoot, hunks);
+    if ("error" in plan) return plan.error;
+    await executePlan(plan.ops);
+    return JSON.stringify({ ok: true, files_patched: plan.patched });
+  } catch (err) {
+    return JSON.stringify({
+      ok: false,
+      error: "io_error",
+      detail: err instanceof Error ? err.message : String(err)
+    });
+  }
+}
+function hunkTargets(hunk) {
+  if (hunk.kind === "update" && hunk.movePath) return [hunk.path, hunk.movePath];
+  return [hunk.path];
 }
 async function buildPlan(projectRoot, hunks) {
+  const dup = firstDuplicateTarget(hunks);
+  if (dup !== null) {
+    return { error: JSON.stringify({ ok: false, error: "duplicate_target", path: dup }) };
+  }
   const ops = [];
   const patched = [];
   for (const hunk of hunks) {
@@ -338,6 +273,16 @@ async function buildPlan(projectRoot, hunks) {
   }
   return { ops, patched };
 }
+function firstDuplicateTarget(hunks) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const hunk of hunks) {
+    for (const t of hunkTargets(hunk)) {
+      if (seen.has(t)) return t;
+      seen.add(t);
+    }
+  }
+  return null;
+}
 async function executePlan(ops) {
   for (const op of ops) {
     if ("rm" in op) {
@@ -348,11 +293,29 @@ async function executePlan(ops) {
     }
   }
 }
+async function pathExists(abs) {
+  try {
+    await stat(abs);
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function planHunk(projectRoot, hunk) {
   const scope = v4aScope(projectRoot, hunk.path);
   if ("error" in scope) return scope;
-  if (hunk.kind === "add") return { ops: [{ write: { abs: scope.abs, content: hunk.content } }] };
-  if (hunk.kind === "delete") return { ops: [{ rm: scope.abs }] };
+  if (hunk.kind === "add") {
+    if (await pathExists(scope.abs)) {
+      return { error: JSON.stringify({ ok: false, error: "file_exists", path: hunk.path }) };
+    }
+    return { ops: [{ write: { abs: scope.abs, content: hunk.content } }] };
+  }
+  if (hunk.kind === "delete") {
+    if (!await pathExists(scope.abs)) {
+      return { error: JSON.stringify({ ok: false, error: "not_found", path: hunk.path }) };
+    }
+    return { ops: [{ rm: scope.abs }] };
+  }
   return planUpdate(projectRoot, hunk, scope.abs);
 }
 async function planUpdate(projectRoot, hunk, abs) {
@@ -386,27 +349,32 @@ async function planUpdate(projectRoot, hunk, abs) {
   if ("error" in dest) return dest;
   return { ops: [{ write: { abs: dest.abs, content: updated } }, { rm: abs }] };
 }
+var FORBIDDEN_SEGMENTS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function isForbiddenRel(rel) {
+  return rel.split(/[/\\]/).filter(Boolean).some((s) => s !== ".env.example" && (FORBIDDEN_SEGMENTS.has(s) || /^\.env\./.test(s)));
+}
 function v4aScope(projectRoot, file) {
-  if (isForbiddenPath(file)) {
-    return { error: JSON.stringify({ ok: false, error: "forbidden_path", path: file }) };
-  }
+  let abs;
   try {
-    const abs = safePathJoin(projectRoot, file);
+    abs = safePathJoin(projectRoot, file);
     assertNoSymlinkEscape(abs, projectRoot);
-    return { abs };
   } catch (err) {
     if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
       return { error: JSON.stringify({ ok: false, error: "path_traversal", path: file }) };
     }
     throw err;
   }
+  if (isForbiddenPath(file) || isForbiddenRel(relative(projectRoot, abs))) {
+    return { error: JSON.stringify({ ok: false, error: "forbidden_path", path: file }) };
+  }
+  return { abs };
 }
 function createSessionArtifactStore(options) {
   const { dir } = options;
   const idStrategy = options.idStrategy ?? ((id) => safeFilenameForId(id));
   const extension = options.extension ?? ".md";
   function path(id) {
-    return safePathJoin$1(dir, `${idStrategy(id)}${extension}`);
+    return safePathJoin(dir, `${idStrategy(id)}${extension}`);
   }
   async function write(id, content) {
     const target = path(id);
@@ -742,25 +710,25 @@ function createSettleGate(timer) {
     }
   };
 }
-function armTimeoutKill(child, timeoutMs, onTimeout, resolve2) {
+function armTimeoutKill(child, timeoutMs, onTimeout, resolve) {
   const timer = setTimeout(() => {
     gate.fire(() => {
       try {
         process.kill(-(child.pid ?? 0), "SIGKILL");
       } catch {
       }
-      resolve2(onTimeout());
+      resolve(onTimeout());
     });
   }, timeoutMs);
   const gate = createSettleGate(timer);
   return gate;
 }
-function attachChildSettlers(child, gate, onClose, onError, resolve2) {
+function attachChildSettlers(child, gate, onClose, onError, resolve) {
   child.on("close", (code) => {
-    gate.fire(() => resolve2(onClose(code)));
+    gate.fire(() => resolve(onClose(code)));
   });
   child.on("error", (err) => {
-    gate.fire(() => resolve2(onError(err)));
+    gate.fire(() => resolve(onError(err)));
   });
 }
 
@@ -827,7 +795,7 @@ function formatGitResult(result, timeoutMs) {
   return JSON.stringify({ ok: true, diff: result.stdout, truncated: result.truncated });
 }
 function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const child = spawn("git", args, { cwd, detached: true, stdio: ["ignore", "pipe", "pipe"] });
     const stdoutChunks = [];
     const stderrChunks = [];
@@ -837,7 +805,7 @@ function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
       child,
       timeoutMs,
       () => ({ kind: "timeout" }),
-      resolve2
+      resolve
     );
     child.stdout.on("data", (chunk) => {
       if (gate.settled()) return;
@@ -867,7 +835,7 @@ function runGitProcess(cwd, args, timeoutMs, maxStdoutBytes) {
         return code === 0 ? { kind: "ok", stdout, truncated } : { kind: "error", stderr };
       },
       (err) => ({ kind: "error", stderr: err.message }),
-      resolve2
+      resolve
     );
   });
 }
@@ -1546,29 +1514,29 @@ function createListDirTool(opts) {
       path: z.string().min(1).describe("Project-relative directory path. Use '.' for root.")
     }),
     handler: async ({ path }, ctx) => {
-      const relative2 = path === "" || path === "." ? "." : path;
-      if (relative2 !== "." && isForbiddenPath(relative2)) {
+      const relative3 = path === "" || path === "." ? "." : path;
+      if (relative3 !== "." && isForbiddenPath(relative3)) {
         return JSON.stringify({ ok: false, error: "forbidden_path", path });
       }
       if (filesystem) {
         const backend = await resolveFilesystem(filesystem, ctx ?? {});
-        return listViaBackend(backend, relative2, path, max);
+        return listViaBackend(backend, relative3, path, max);
       }
-      return listViaLocalFs(projectRoot, relative2, path, max);
+      return listViaLocalFs(projectRoot, relative3, path, max);
     }
   });
 }
-async function listViaLocalFs(projectRoot, relative2, originalPath, max) {
-  const boundary = resolveDirBoundary(relative2, projectRoot, originalPath);
+async function listViaLocalFs(projectRoot, relative3, originalPath, max) {
+  const boundary = resolveDirBoundary(relative3, projectRoot, originalPath);
   if ("error" in boundary) return boundary.error;
   const readResult = await readDirSafe(boundary.absolutePath, originalPath);
   if ("error" in readResult) return readResult.error;
   return formatListing(readResult.dirents, max);
 }
-async function listViaBackend(backend, relative2, originalPath, max) {
+async function listViaBackend(backend, relative3, originalPath, max) {
   let names;
   try {
-    names = await backend.list(relative2);
+    names = await backend.list(relative3);
   } catch (err) {
     if (err instanceof FileNotFoundError) {
       return JSON.stringify({ ok: false, error: "not_found", path: originalPath });
@@ -1582,7 +1550,7 @@ async function listViaBackend(backend, relative2, originalPath, max) {
   const windowed = names.slice(0, max);
   const entries = await Promise.all(
     windowed.map(async (name) => {
-      const child = relative2 === "." ? name : `${relative2}/${name}`;
+      const child = relative3 === "." ? name : `${relative3}/${name}`;
       let type = "file";
       try {
         type = (await backend.stat(child)).isDirectory ? "directory" : "file";
@@ -1593,9 +1561,9 @@ async function listViaBackend(backend, relative2, originalPath, max) {
   );
   return JSON.stringify({ ok: true, entries, truncated: totalCount > max, totalCount });
 }
-function resolveDirBoundary(relative2, projectRoot, originalPath) {
+function resolveDirBoundary(relative3, projectRoot, originalPath) {
   try {
-    const absolutePath = relative2 === "." ? projectRoot : safePathJoin(projectRoot, relative2);
+    const absolutePath = relative3 === "." ? projectRoot : safePathJoin(projectRoot, relative3);
     assertNoSymlinkEscape(absolutePath, projectRoot);
     return { absolutePath };
   } catch (err) {
@@ -1817,22 +1785,22 @@ function createReadFileTool(opts) {
 }
 async function readViaBackend(backend, path, view, onRead) {
   try {
-    const stat2 = await backend.stat(path);
-    if (stat2.size > MAX_FILE_SIZE) {
+    const stat3 = await backend.stat(path);
+    if (stat3.size > MAX_FILE_SIZE) {
       return JSON.stringify({
         ok: false,
         error: "too_large",
         path,
-        size: stat2.size,
+        size: stat3.size,
         limit: MAX_FILE_SIZE
       });
     }
     const raw = await backend.readFile(path);
     if (raw.includes("\0")) {
-      return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
+      return JSON.stringify({ ok: false, error: "binary_file", path, size: stat3.size });
     }
-    onRead?.(stat2.mtimeMs);
-    return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat2.size });
+    onRead?.(stat3.mtimeMs);
+    return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat3.size });
   } catch (err) {
     if (err instanceof FileNotFoundError) {
       return JSON.stringify({ ok: false, error: "not_found", path });
@@ -1871,22 +1839,22 @@ async function openHandleSafe(absolutePath, path) {
   }
 }
 async function readContent(handle, path, view, onRead) {
-  const stat2 = await handle.stat();
-  if (stat2.size > MAX_FILE_SIZE) {
+  const stat3 = await handle.stat();
+  if (stat3.size > MAX_FILE_SIZE) {
     return JSON.stringify({
       ok: false,
       error: "too_large",
       path,
-      size: stat2.size,
+      size: stat3.size,
       limit: MAX_FILE_SIZE
     });
   }
-  if (await isBinaryProbe(handle, Number(stat2.size))) {
-    return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
+  if (await isBinaryProbe(handle, Number(stat3.size))) {
+    return JSON.stringify({ ok: false, error: "binary_file", path, size: stat3.size });
   }
   const raw = await handle.readFile({ encoding: "utf-8" });
-  onRead?.(stat2.mtimeMs);
-  return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat2.size });
+  onRead?.(stat3.mtimeMs);
+  return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat3.size });
 }
 async function isBinaryProbe(handle, size) {
   const probeLen = Math.min(BINARY_PROBE_BYTES, size);
@@ -2020,7 +1988,7 @@ function appendCapped(chunks, chunk, current, cap) {
   return current + chunk.length;
 }
 function runProcess(cwd, command, args, timeoutMs, maxStdoutBytes) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const child = spawn(command, args, {
       cwd,
       detached: true,
@@ -2033,7 +2001,7 @@ function runProcess(cwd, command, args, timeoutMs, maxStdoutBytes) {
       child,
       timeoutMs,
       () => ({ kind: "timeout" }),
-      resolve2
+      resolve
     );
     child.stdout.on("data", (chunk) => {
       if (gate.settled()) return;
@@ -2052,7 +2020,7 @@ function runProcess(cwd, command, args, timeoutMs, maxStdoutBytes) {
         exitCode: code ?? 0
       }),
       (err) => ({ kind: "spawn_error", message: err.message }),
-      resolve2
+      resolve
     );
   });
 }
@@ -2303,7 +2271,7 @@ function createShellTool(opts) {
   });
 }
 function runShell(cwd, command, timeoutMs) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve) => {
     const child = spawn("/bin/sh", ["-c", command], {
       cwd,
       detached: true,
@@ -2317,7 +2285,7 @@ function runShell(cwd, command, timeoutMs) {
       child,
       timeoutMs,
       () => ({ kind: "timeout" }),
-      (result) => resolve2(formatResult(result, timeoutMs))
+      (result) => resolve(formatResult(result, timeoutMs))
     );
     child.stdout.on("data", (chunk) => {
       if (gate.settled()) return;
@@ -2355,7 +2323,7 @@ function runShell(cwd, command, timeoutMs) {
         exitCode: code
       }),
       (err) => ({ kind: "error", message: err.message }),
-      (result) => resolve2(formatResult(result, timeoutMs))
+      (result) => resolve(formatResult(result, timeoutMs))
     );
   });
 }
@@ -2802,12 +2770,12 @@ async function writeViaBackend(backend, path, content, guard) {
       if (rbw) return rbw;
       expectedMtime = current ?? void 0;
     }
-    const stat2 = await backend.writeFile(
+    const stat3 = await backend.writeFile(
       path,
       content,
       expectedMtime !== void 0 ? { expectedMtime } : void 0
     );
-    return JSON.stringify({ ok: true, path, bytes: stat2.size });
+    return JSON.stringify({ ok: true, path, bytes: stat3.size });
   } catch (err) {
     return backendErrorToJson(err, path);
   }
@@ -2835,8 +2803,8 @@ async function isBinaryFile(absolutePath) {
     return false;
   }
   try {
-    const stat2 = await handle.stat();
-    const probeLen = Math.min(BINARY_PROBE_BYTES3, Number(stat2.size));
+    const stat3 = await handle.stat();
+    const probeLen = Math.min(BINARY_PROBE_BYTES3, Number(stat3.size));
     if (probeLen <= 0) return false;
     const probe = Buffer.alloc(probeLen);
     const { bytesRead } = await handle.read(probe, 0, probeLen, 0);