@theokit/sdk-tools 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -40,13 +40,13 @@
 
   A pluggable filesystem _storage_ provider, the storage-side twin of `@theokit/sdk/sandbox`. `FilesystemBackend` is an abstract class with four methods (`readFile` / `writeFile` / `stat` / `list`), an `exists()` derived on the base, a boundary `basePath`, a `readOnly` flag, structured `stat().mtimeMs` (the read-before-write oracle for SE32), and typed errors (`FileNotFoundError` / `FilesystemSecurityError` / `FilesystemReadOnlyError` / `StaleFileError`). `LocalFilesystem` is the local-process implementation, boundary-enforced by reusing the core path-guard (traversal + symlink escape → `FilesystemSecurityError`). `FilesystemProvider` + `resolveFilesystem` support a per-request resolver `(ctx) => FilesystemBackend` for multi-tenant roots.
 
-  Unlike `SandboxBackend` (whose file ops shell out via `execute`, require command execution, and give no structured `stat`), a `FilesystemBackend` serves a filesystem-only workspace with no sandbox — see ADR 0011 for why file ops are NOT routed through `SandboxBackend`. `@theokit/sdk-tools`' `createWriteFileTool` now accepts an optional `filesystem` backend (writes route through it; omitted ⇒ identical local-`projectRoot` behavior). This is the backend seam, NOT a bundled `Workspace` and NOT a new toolset — bring-your-own-tools stands; `mounts`/FUSE, S3/GCS, and LSP remain out of core. From the Mastra Workspaces comparison (SDK Evolution roadmap SE31).
+  Unlike `SandboxBackend` (whose file ops shell out via `execute`, require command execution, and give no structured `stat`), a `FilesystemBackend` serves a filesystem-only workspace with no sandbox — see ADR 0011 for why file ops are NOT routed through `SandboxBackend`. `@theokit/sdk-tools`' `createWriteFileTool` now accepts an optional `filesystem` backend (writes route through it; omitted ⇒ identical local-`projectRoot` behavior). This is the backend seam, NOT a bundled `Workspace` and NOT a new toolset — bring-your-own-tools stands; `mounts`/FUSE, S3/GCS, and LSP remain out of core. (SDK Evolution roadmap SE31.)
 
 - 84df83a: **SE32 — read-before-write safety (`requireReadBeforeWrite` + `ReadTracker`).**
 
   An opt-in guard on `createWriteFileTool` that refuses to blindly overwrite a file the agent has not seen. A per-run `ReadTracker` (exported from `@theokit/sdk-tools`) records each file's mtime when `createReadFileTool` reads it; when `createWriteFileTool` is created with `{ requireReadBeforeWrite: true, readTracker }`, a write is refused with `read_required` if the existing file was never read, or `stale_file` if it changed on disk since it was read. A NEW file writes freely (nothing to clobber). Default OFF — omitting the flag preserves current behavior exactly.
 
-  Works on both the local `projectRoot` path and the SE31 `filesystem` backend path (the backend also gets `expectedMtime` forwarded so it re-checks at write time — TOCTOU defense). The tracker is deliberately per-instance, not a global singleton, so state never leaks across runs. `edit_file` already has implicit read-before-write safety via `old_string` content matching, so the guard targets the blind-overwrite path (`write_file`). Mirrors Mastra Workspaces' read-before-write (`FileReadRequiredError` / `StaleFileError`). From the Mastra Workspaces comparison (SDK Evolution roadmap SE32).
+  Works on both the local `projectRoot` path and the SE31 `filesystem` backend path (the backend also gets `expectedMtime` forwarded so it re-checks at write time — TOCTOU defense). The tracker is deliberately per-instance, not a global singleton, so state never leaks across runs. `edit_file` already has implicit read-before-write safety via `old_string` content matching, so the guard targets the blind-overwrite path (`write_file`). Refusals surface as `FileReadRequiredError` / `StaleFileError`. (SDK Evolution roadmap SE32.)
 
 ## 0.8.0
 

package/README.md

@@ -75,7 +75,7 @@ After (2.x):
 import { createReadFileTool } from "@theokit/sdk-tools";
 ```
 
-See `docs/migration/1-x-to-2-0.md` in the monorepo root.
+See the monorepo `CHANGELOG.md` for the 1.x → 2.0 package-split migration notes.
 
 ## License
 

package/dist/index.cjs

@@ -265,6 +265,90 @@ function createSessionArtifactStore(options) {
   }
   return { write, read, has, list, path };
 }
+
+// src/internal/context-match.ts
+var ContextMatchError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "ContextMatchError";
+    this.reason = reason;
+  }
+};
+function normalizeUnicode(s) {
+  return s.replace(/[‐-―−]/g, "-").replace(/[‘-‛]/g, "'").replace(/[“-‟]/g, '"').replace(/[ -   　]/g, " ");
+}
+var LINE_MATCH_LADDER = [
+  (s) => s,
+  // exact
+  (s) => s.replace(/\s+$/, ""),
+  // rstrip (ignore trailing whitespace)
+  (s) => s.trim(),
+  // trim (ignore leading + trailing)
+  (s) => normalizeUnicode(s).trim()
+  // unicode + trim (loosest)
+];
+function matchesAt(lines, pattern, i, norm) {
+  for (let p = 0; p < pattern.length; p++) {
+    const lineAt = lines[i + p];
+    const patAt = pattern[p];
+    if (lineAt === void 0 || patAt === void 0 || norm(lineAt) !== norm(patAt)) return false;
+  }
+  return true;
+}
+function findHits(lines, pattern, norm) {
+  const hits = [];
+  for (let i = 0; i + pattern.length <= lines.length; i++) {
+    if (matchesAt(lines, pattern, i, norm)) hits.push(i);
+  }
+  return hits;
+}
+function seekUniqueLineMatch(lines, pattern, find) {
+  if (pattern.length === 0 || pattern.length > lines.length) return null;
+  for (const norm of LINE_MATCH_LADDER) {
+    const hits = findHits(lines, pattern, norm);
+    if (hits.length === 1) return hits[0] ?? null;
+    if (hits.length > 1) {
+      throw new ContextMatchError(
+        "ambiguous",
+        `target text is ambiguous (multiple matches); include more context:
+${find}`
+      );
+    }
+  }
+  return null;
+}
+function replaceUnique(content, find, replace) {
+  if (find === "") {
+    throw new ContextMatchError(
+      "empty",
+      "empty find is not a valid target; provide the text to replace"
+    );
+  }
+  const first = content.indexOf(find);
+  if (first !== -1) {
+    if (content.indexOf(find, first + 1) !== -1) {
+      throw new ContextMatchError(
+        "ambiguous",
+        `target text is ambiguous (multiple matches); include more context:
+${find}`
+      );
+    }
+    return content.slice(0, first) + replace + content.slice(first + find.length);
+  }
+  const lines = content.split("\n");
+  const at = seekUniqueLineMatch(lines, find.split("\n"), find);
+  if (at === null) {
+    throw new ContextMatchError("not_found", `target text not found:
+${find}`);
+  }
+  const patternLen = find.split("\n").length;
+  const matchedCrlf = patternLen > 0 && lines.slice(at, at + patternLen).every((l) => l.endsWith("\r"));
+  const replaceLines = matchedCrlf ? replace.split("\n").map((l) => l.endsWith("\r") ? l : `${l}\r`) : replace.split("\n");
+  return [...lines.slice(0, at), ...replaceLines, ...lines.slice(at + patternLen)].join("\n");
+}
+
+// src/edit-file.ts
 function createEditFileTool(opts) {
   const { projectRoot } = opts;
   return sdk.Tool.create({
@@ -306,26 +390,36 @@ function createEditFileTool(opts) {
       const exactIdx = content.indexOf(old_string);
       if (exactIdx !== -1) {
         await promises.copyFile(absolutePath, `${absolutePath}.bak`);
-        const result2 = content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length);
-        await promises.writeFile(absolutePath, result2, "utf-8");
+        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) {
-        return JSON.stringify({ ok: false, error: "no_match", path });
+      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 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 });
     }
   });
 }
@@ -990,6 +1084,14 @@ function withDescription(tool, description) {
     handler: tool.handler
   };
 }
+function withName(tool, name) {
+  return {
+    name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: tool.handler
+  };
+}
 function esc(s) {
   return String(s).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
@@ -2242,6 +2344,7 @@ async function isBinaryFile(absolutePath) {
 }
 
 exports.CatastrophicCommandError = CatastrophicCommandError;
+exports.ContextMatchError = ContextMatchError;
 exports.DEFAULT_TOOL_GUIDANCE = DEFAULT_TOOL_GUIDANCE;
 exports.ReadTracker = ReadTracker;
 exports.ReasoningTools = ReasoningTools;
@@ -2278,12 +2381,14 @@ exports.injectGuidance = injectGuidance;
 exports.isBlockedIp = isBlockedIp;
 exports.isCommandAllowed = isCommandAllowed;
 exports.renderToolList = renderToolList;
+exports.replaceUnique = replaceUnique;
 exports.resolveAndScreen = resolveAndScreen;
 exports.screenedFetch = screenedFetch;
 exports.todoItemsToPlanNodes = todoItemsToPlanNodes;
 exports.truncateOutput = truncateOutput;
 exports.withDefaultGuidance = withDefaultGuidance;
 exports.withDescription = withDescription;
+exports.withName = withName;
 exports.withShellExitGuidance = withShellExitGuidance;
 exports.withToolResultGuidance = withToolResultGuidance;
 //# sourceMappingURL=index.cjs.map