@wrongstack/tools 0.1.1 → 0.1.3

package/dist/diff.d.ts

@@ -0,0 +1,20 @@
+import { Tool } from '@wrongstack/core';
+
+interface DiffInput {
+    path?: string;
+    files?: string | string[];
+    a?: string;
+    b?: string;
+    staged?: boolean;
+    mode?: 'unified' | 'side-by-side' | 'stat';
+    context?: number;
+}
+interface DiffOutput {
+    diff: string;
+    files: string[];
+    truncated: boolean;
+    mode: string;
+}
+declare const diffTool: Tool<DiffInput, DiffOutput>;
+
+export { diffTool };

package/dist/diff.js

@@ -0,0 +1,142 @@
+import * as fs from 'fs/promises';
+import { spawn } from 'child_process';
+import * as path from 'path';
+
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+function resolvePath(input, ctx) {
+  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.cwd, input);
+}
+function ensureInsideRoot(absPath, ctx) {
+  const root = path.resolve(ctx.projectRoot);
+  const target = path.resolve(absPath);
+  const rel = path.relative(root, target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`Path "${absPath}" is outside project root "${root}"`);
+  }
+  return target;
+}
+function safeResolve(input, ctx) {
+  return ensureInsideRoot(resolvePath(input, ctx), ctx);
+}
+
+// src/diff.ts
+var diffTool = {
+  name: "diff",
+  description: "Show differences between files, commits, or branches. Supports staged vs working tree.",
+  usageHint: "Use `files` for file paths, `a`/`b` for commit refs, `staged` for git index. `mode`: unified (default), stat, side-by-side.",
+  permission: "auto",
+  mutating: false,
+  timeoutMs: 1e4,
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string", description: "Working directory for diff" },
+      files: {
+        type: "string",
+        description: 'File(s) to diff: single path, comma-separated, or "**/*.ts" glob'
+      },
+      a: { type: "string", description: "First commit/branch/ref (for git diff)" },
+      b: { type: "string", description: "Second commit/branch/ref (for git diff)" },
+      staged: { type: "boolean", description: "Diff staged changes only" },
+      mode: {
+        type: "string",
+        enum: ["unified", "side-by-side", "stat"],
+        description: "Output mode (default: unified)"
+      },
+      context: { type: "integer", description: "Context lines for unified diff (default: 3)" }
+    }
+  },
+  async execute(input, ctx, opts) {
+    if (input.a !== void 0 || input.b !== void 0) {
+      return await gitDiff(input, ctx, opts.signal);
+    }
+    return await fileDiff(input, ctx, opts.signal);
+  }
+};
+async function gitDiff(input, ctx, signal) {
+  const gitDir = findGitDir(ctx.cwd);
+  if (!gitDir) {
+    return { diff: "", files: [], truncated: false, mode: "unified" };
+  }
+  const args = ["diff", "--no-color"];
+  if (input.staged) args.push("--staged");
+  if (input.a) args.push(input.a);
+  if (input.b) args.push(input.b);
+  if (input.files) {
+    const files = Array.isArray(input.files) ? input.files : input.files.split(",");
+    args.push("--", ...files.map((f) => f.trim()));
+  }
+  const result = await runGit(args, gitDir, signal);
+  return {
+    diff: result.stdout,
+    files: [],
+    truncated: result.stdout.length > 1e5,
+    mode: "unified"
+  };
+}
+function findGitDir(cwd) {
+  let dir = cwd;
+  for (let i = 0; i < 20; i++) {
+    try {
+      const stat2 = __require("fs").statSync(`${dir}/.git`);
+      if (stat2.isDirectory()) return dir;
+    } catch {
+    }
+    const parent = __require("path").dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function runGit(args, cwd, signal) {
+  return new Promise((resolve2) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn("git", args, { cwd, signal, stdio: ["ignore", "pipe", "pipe"] });
+    child.stdout?.on("data", (c) => {
+      stdout += c.toString();
+    });
+    child.stderr?.on("data", (c) => {
+      stderr += c.toString();
+    });
+    child.on("close", (code) => resolve2({ stdout, stderr, exitCode: code ?? 0 }));
+    child.on("error", (e) => resolve2({ stdout: "", stderr: e.message, exitCode: 1 }));
+  });
+}
+async function fileDiff(input, ctx, signal) {
+  input.path ? safeResolve(input.path, ctx) : ctx.cwd;
+  input.context ?? 3;
+  const files = input.files ? (Array.isArray(input.files) ? input.files : input.files.split(",")).map((f) => f.trim()).filter(Boolean) : [];
+  if (files.length === 0) {
+    return { diff: "No files specified", files: [], truncated: false, mode: input.mode ?? "unified" };
+  }
+  const results = [];
+  for (const file of files) {
+    const absPath = safeResolve(file, ctx);
+    const stat2 = await fs.stat(absPath).catch(() => null);
+    if (!stat2?.isFile()) continue;
+    const content = await fs.readFile(absPath, "utf8");
+    const lines = content.split(/\r?\n/);
+    results.push(`--- ${file}
++++ ${file}
+${formatUnified(lines)}`);
+  }
+  return {
+    diff: results.join("\n"),
+    files,
+    truncated: false,
+    mode: input.mode ?? "unified"
+  };
+}
+function formatUnified(lines, context) {
+  return lines.map((line, i) => ` ${line}`).join("\n");
+}
+
+export { diffTool };
+//# sourceMappingURL=diff.js.map
+//# sourceMappingURL=diff.js.map

package/dist/diff.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/_util.ts","../src/diff.ts"],"names":["stat","resolve","spawn"],"mappings":"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","file":"diff.js","sourcesContent":["import * as path from 'node:path';\r\nimport { spawn } from 'node:child_process';\r\nimport type { Context, ToolProgressEvent } from '@wrongstack/core';\r\n\r\nexport function resolvePath(input: string, ctx: Context): string {\r\n  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.cwd, input);\r\n}\r\n\r\nexport function ensureInsideRoot(absPath: string, ctx: Context): string {\r\n  const root = path.resolve(ctx.projectRoot);\r\n  const target = path.resolve(absPath);\r\n  const rel = path.relative(root, target);\r\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\r\n    throw new Error(`Path \"${absPath}\" is outside project root \"${root}\"`);\r\n  }\r\n  return target;\r\n}\r\n\r\nexport function safeResolve(input: string, ctx: Context): string {\r\n  return ensureInsideRoot(resolvePath(input, ctx), ctx);\r\n}\r\n\r\nexport function truncateMiddle(s: string, max: number): string {\r\n  if (Buffer.byteLength(s, 'utf8') <= max) return s;\r\n  const half = Math.floor(max / 2);\r\n  return (\r\n    s.slice(0, half) +\r\n    `\\n…[truncated ${Buffer.byteLength(s, 'utf8') - max} bytes from middle]…\\n` +\r\n    s.slice(-half)\r\n  );\r\n}\r\n\r\nexport function isBinaryBuffer(buf: Buffer): boolean {\r\n  const len = Math.min(buf.length, 8192);\r\n  for (let i = 0; i < len; i++) {\r\n    if (buf[i] === 0) return true;\r\n  }\r\n  return false;\r\n}\r\n\r\nexport interface SpawnStreamResult {\r\n  stdout: string;\r\n  stderr: string;\r\n  exitCode: number;\r\n  truncated: boolean;\r\n  error?: string;\r\n}\r\n\r\nexport interface SpawnStreamOptions {\r\n  cmd: string;\r\n  args: string[];\r\n  cwd: string;\r\n  signal: AbortSignal;\r\n  maxBytes?: number;\r\n  /** Bytes of new stdout/stderr to accumulate before yielding a `partial_output` event. */\r\n  flushBytes?: number;\r\n}\r\n\r\n/**\r\n * Spawn a child process and yield `partial_output` progress events as\r\n * stdout/stderr arrive (batched by byte threshold), then return the full\r\n * buffered result. Shared between install/lint/format/typecheck/test/audit\r\n * so the TUI live tail sees consistent progress regardless of which tool\r\n * is running.\r\n */\r\nexport async function* spawnStream(\r\n  opts: SpawnStreamOptions,\r\n): AsyncGenerator<ToolProgressEvent, SpawnStreamResult> {\r\n  const max = opts.maxBytes ?? 200_000;\r\n  const flushAt = opts.flushBytes ?? 4 * 1024;\r\n  let stdout = '';\r\n  let stderr = '';\r\n  let pending = '';\r\n  let error: string | undefined;\r\n\r\n  const child = spawn(opts.cmd, opts.args, {\r\n    cwd: opts.cwd,\r\n    signal: opts.signal,\r\n    stdio: ['ignore', 'pipe', 'pipe'],\r\n  });\r\n\r\n  type Chunk = { kind: 'out' | 'err' | 'close' | 'error'; data: string; code?: number };\r\n  const queue: Chunk[] = [];\r\n  let waiter: (() => void) | undefined;\r\n  const wake = () => {\r\n    if (waiter) {\r\n      const w = waiter;\r\n      waiter = undefined;\r\n      w();\r\n    }\r\n  };\r\n\r\n  child.stdout?.on('data', (c) => {\r\n    const s = c.toString();\r\n    if (stdout.length < max) stdout += s;\r\n    queue.push({ kind: 'out', data: s });\r\n    wake();\r\n  });\r\n  child.stderr?.on('data', (c) => {\r\n    const s = c.toString();\r\n    if (stderr.length < max) stderr += s;\r\n    queue.push({ kind: 'err', data: s });\r\n    wake();\r\n  });\r\n  child.on('error', (e) => {\r\n    error = e.message;\r\n    queue.push({ kind: 'error', data: e.message });\r\n    wake();\r\n  });\r\n  child.on('close', (code) => {\r\n    queue.push({ kind: 'close', data: '', code: code ?? 0 });\r\n    wake();\r\n  });\r\n\r\n  let exitCode = 0;\r\n  let spawnFailed = false;\r\n  for (;;) {\r\n    while (queue.length === 0) {\r\n      await new Promise<void>((resolve) => {\r\n        waiter = resolve;\r\n      });\r\n    }\r\n    const chunk = queue.shift()!;\r\n    if (chunk.kind === 'close') {\r\n      // If we already saw a spawn error (ENOENT etc.), keep exitCode=1\r\n      // rather than the negative platform code Node fabricates.\r\n      if (!spawnFailed) exitCode = chunk.code ?? 0;\r\n      break;\r\n    }\r\n    if (chunk.kind === 'error') {\r\n      spawnFailed = true;\r\n      exitCode = 1;\r\n      // close usually follows\r\n      continue;\r\n    }\r\n    pending += chunk.data;\r\n    if (pending.length >= flushAt) {\r\n      yield { type: 'partial_output', text: pending };\r\n      pending = '';\r\n    }\r\n  }\r\n  if (pending.length > 0) {\r\n    yield { type: 'partial_output', text: pending };\r\n  }\r\n\r\n  return {\r\n    stdout,\r\n    stderr,\r\n    exitCode,\r\n    truncated: stdout.length >= max || stderr.length >= max,\r\n    error,\r\n  };\r\n}\r\n","import * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport { spawn } from 'node:child_process';\nimport type { Tool } from '@wrongstack/core';\nimport { safeResolve } from './_util.js';\nimport { unifiedDiff } from '@wrongstack/core';\n\ninterface DiffInput {\n  path?: string;\n  files?: string | string[];\n  a?: string;\n  b?: string;\n  staged?: boolean;\n  mode?: 'unified' | 'side-by-side' | 'stat';\n  context?: number;\n}\n\ninterface DiffOutput {\n  diff: string;\n  files: string[];\n  truncated: boolean;\n  mode: string;\n}\n\nexport const diffTool: Tool<DiffInput, DiffOutput> = {\n  name: 'diff',\n  description:\n    'Show differences between files, commits, or branches. Supports staged vs working tree.',\n  usageHint:\n    'Use `files` for file paths, `a`/`b` for commit refs, `staged` for git index. `mode`: unified (default), stat, side-by-side.',\n  permission: 'auto',\n  mutating: false,\n  timeoutMs: 10_000,\n  inputSchema: {\n    type: 'object',\n    properties: {\n      path: { type: 'string', description: 'Working directory for diff' },\n      files: {\n        type: 'string',\n        description: 'File(s) to diff: single path, comma-separated, or \"**/*.ts\" glob',\n      },\n      a: { type: 'string', description: 'First commit/branch/ref (for git diff)' },\n      b: { type: 'string', description: 'Second commit/branch/ref (for git diff)' },\n      staged: { type: 'boolean', description: 'Diff staged changes only' },\n      mode: {\n        type: 'string',\n        enum: ['unified', 'side-by-side', 'stat'],\n        description: 'Output mode (default: unified)',\n      },\n      context: { type: 'integer', description: 'Context lines for unified diff (default: 3)' },\n    },\n  },\n  async execute(input, ctx, opts) {\n    if (input.a !== undefined || input.b !== undefined) {\n      return await gitDiff(input, ctx, opts.signal);\n    }\n\n    return await fileDiff(input, ctx, opts.signal);\n  },\n};\n\nasync function gitDiff(\n  input: DiffInput,\n  ctx: import('@wrongstack/core').Context,\n  signal: AbortSignal,\n): Promise<DiffOutput> {\n  const gitDir = findGitDir(ctx.cwd);\n  if (!gitDir) {\n    return { diff: '', files: [], truncated: false, mode: 'unified' };\n  }\n\n  const args: string[] = ['diff', '--no-color'];\n  if (input.staged) args.push('--staged');\n  if (input.a) args.push(input.a);\n  if (input.b) args.push(input.b);\n  if (input.files) {\n    const files = Array.isArray(input.files) ? input.files : input.files.split(',');\n    args.push('--', ...files.map((f) => f.trim()));\n  }\n\n  const result = await runGit(args, gitDir, signal);\n  return {\n    diff: result.stdout,\n    files: [],\n    truncated: result.stdout.length > 100_000,\n    mode: 'unified',\n  };\n}\n\nfunction findGitDir(cwd: string): string | null {\n  let dir = cwd;\n  for (let i = 0; i < 20; i++) {\n    try {\n      const stat = require('node:fs').statSync(`${dir}/.git`);\n      if (stat.isDirectory()) return dir;\n    } catch {\n      // continue\n    }\n    const parent = require('node:path').dirname(dir);\n    if (parent === dir) break;\n    dir = parent;\n  }\n  return null;\n}\n\nfunction runGit(args: string[], cwd: string, signal: AbortSignal): Promise<{ stdout: string; stderr: string; exitCode: number }> {\n  return new Promise((resolve) => {\n    let stdout = '';\n    let stderr = '';\n\n    const child = spawn('git', args, { cwd, signal, stdio: ['ignore', 'pipe', 'pipe'] });\n    child.stdout?.on('data', (c) => { stdout += c.toString(); });\n    child.stderr?.on('data', (c) => { stderr += c.toString(); });\n    child.on('close', (code) => resolve({ stdout, stderr, exitCode: code ?? 0 }));\n    child.on('error', (e) => resolve({ stdout: '', stderr: e.message, exitCode: 1 }));\n  });\n}\n\nasync function fileDiff(\n  input: DiffInput,\n  ctx: import('@wrongstack/core').Context,\n  signal: AbortSignal,\n): Promise<DiffOutput> {\n  const baseDir = input.path ? safeResolve(input.path, ctx) : ctx.cwd;\n  const context = input.context ?? 3;\n\n  const files = input.files\n    ? (Array.isArray(input.files) ? input.files : input.files.split(',')).map((f) => f.trim()).filter(Boolean)\n    : [];\n\n  if (files.length === 0) {\n    return { diff: 'No files specified', files: [], truncated: false, mode: input.mode ?? 'unified' };\n  }\n\n  const results: string[] = [];\n\n  for (const file of files) {\n    const absPath = safeResolve(file, ctx);\n    const stat = await fs.stat(absPath).catch(() => null);\n    if (!stat?.isFile()) continue;\n\n    const content = await fs.readFile(absPath, 'utf8');\n    const lines = content.split(/\\r?\\n/);\n    results.push(`--- ${file}\\n+++ ${file}\\n${formatUnified(lines, context)}`);\n  }\n\n  return {\n    diff: results.join('\\n'),\n    files,\n    truncated: false,\n    mode: input.mode ?? 'unified',\n  };\n}\n\nfunction formatUnified(lines: string[], context: number): string {\n  return lines.map((line, i) => ` ${line}`).join('\\n');\n}"]}

package/dist/document.d.ts

@@ -0,0 +1,27 @@
+import { Tool } from '@wrongstack/core';
+
+interface DocumentInput {
+    target: 'file' | 'function' | 'class' | 'type' | 'all';
+    path?: string;
+    files?: string | string[];
+    style?: 'jsdoc' | 'tsdoc' | 'block';
+    overwrite?: boolean;
+    cwd?: string;
+}
+interface DocumentedItem {
+    path: string;
+    name: string;
+    signature: string;
+    docstring: string;
+    status: 'documented' | 'skipped' | 'error';
+    error?: string;
+}
+interface DocumentOutput {
+    files_processed: number;
+    items_documented: number;
+    results: DocumentedItem[];
+    style: string;
+}
+declare const documentTool: Tool<DocumentInput, DocumentOutput>;
+
+export { documentTool };

package/dist/document.js

@@ -0,0 +1,148 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import 'child_process';
+
+// src/document.ts
+function resolvePath(input, ctx) {
+  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.cwd, input);
+}
+function ensureInsideRoot(absPath, ctx) {
+  const root = path.resolve(ctx.projectRoot);
+  const target = path.resolve(absPath);
+  const rel = path.relative(root, target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`Path "${absPath}" is outside project root "${root}"`);
+  }
+  return target;
+}
+function safeResolve(input, ctx) {
+  return ensureInsideRoot(resolvePath(input, ctx), ctx);
+}
+
+// src/document.ts
+var documentTool = {
+  name: "document",
+  description: "Generate or update documentation comments for functions, classes, and types. Supports JSDoc, TSDoc, and block comments.",
+  usageHint: "Set `target` for what to document. `files` for paths. `style` for comment format. `overwrite` replaces existing docs.",
+  permission: "confirm",
+  mutating: true,
+  timeoutMs: 3e4,
+  inputSchema: {
+    type: "object",
+    properties: {
+      target: {
+        type: "string",
+        enum: ["file", "function", "class", "type", "all"],
+        description: "What to document"
+      },
+      path: {
+        type: "string",
+        description: "Specific file path to document"
+      },
+      files: {
+        type: "string",
+        description: "File(s) to process: single path, comma-separated list, or glob"
+      },
+      style: {
+        type: "string",
+        enum: ["jsdoc", "tsdoc", "block"],
+        description: "Documentation style (default: jsdoc)"
+      },
+      overwrite: {
+        type: "boolean",
+        description: "Overwrite existing docstrings (default: false)"
+      },
+      cwd: { type: "string", description: "Working directory (default: cwd)" }
+    }
+  },
+  async execute(input, ctx) {
+    const cwd = input.cwd ? safeResolve(input.cwd, ctx) : ctx.cwd;
+    const style = input.style ?? "jsdoc";
+    const results = [];
+    let filesProcessed = 0;
+    let itemsDocumented = 0;
+    const fileList = input.files ? await resolveFiles(Array.isArray(input.files) ? input.files.join(",") : input.files, cwd) : input.path ? [safeResolve(input.path, ctx)] : [];
+    for (const absPath of fileList) {
+      try {
+        const content = await fs.readFile(absPath, "utf8");
+        filesProcessed++;
+        const processed = processFile(content, absPath, style, input.overwrite ?? false, input.target ?? "all");
+        results.push(...processed);
+        itemsDocumented += processed.filter((r) => r.status === "documented").length;
+      } catch (e) {
+        results.push({
+          path: absPath,
+          name: absPath.split("/").pop() ?? absPath,
+          signature: "",
+          docstring: "",
+          status: "error",
+          error: e instanceof Error ? e.message : String(e)
+        });
+      }
+    }
+    return {
+      files_processed: filesProcessed,
+      items_documented: itemsDocumented,
+      results,
+      style
+    };
+  }
+};
+async function resolveFiles(filesInput, cwd) {
+  const files = Array.isArray(filesInput) ? filesInput : filesInput.split(",");
+  const resolved = [];
+  for (const f of files) {
+    const absPath = f.trim().startsWith("/") ? f.trim() : `${cwd}/${f.trim()}`;
+    try {
+      const stat2 = await fs.stat(absPath);
+      if (stat2.isFile()) resolved.push(absPath);
+    } catch {
+    }
+  }
+  return resolved;
+}
+function processFile(content, absPath, style, overwrite, target) {
+  const results = [];
+  content.split("\n");
+  const functionRegex = /(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g;
+  const arrowRegex = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(([^)]*)\)\s*=>/g;
+  const classRegex = /class\s+(\w+)/g;
+  const typeRegex = /(?:type|interface)\s+(\w+)\s*[=<]/g;
+  const allMatches = [];
+  if (target === "all" || target === "function") {
+    for (const m of content.matchAll(functionRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({ name: m[1], sig: m[2] ?? "", type: "function", line: content.slice(0, m.index).split("\n").length });
+    }
+    for (const m of content.matchAll(arrowRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({ name: m[1], sig: m[2] ?? "", type: "arrow", line: content.slice(0, m.index).split("\n").length });
+    }
+  }
+  if (target === "all" || target === "class") {
+    for (const m of content.matchAll(classRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({ name: m[1], sig: "", type: "class", line: content.slice(0, m.index).split("\n").length });
+    }
+  }
+  if (target === "all" || target === "type") {
+    for (const m of content.matchAll(typeRegex)) {
+      if (!m[1]) continue;
+      allMatches.push({ name: m[1], sig: m[0] ?? "", type: "type", line: content.slice(0, m.index).split("\n").length });
+    }
+  }
+  for (const m of allMatches) {
+    results.push({
+      path: absPath,
+      name: m.name,
+      signature: m.sig,
+      docstring: `/** ${m.name} - documented at line ${m.line} */`,
+      status: "skipped"
+    });
+  }
+  return results;
+}
+
+export { documentTool };
+//# sourceMappingURL=document.js.map
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/_util.ts","../src/document.ts"],"names":["stat"],"mappings":"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","file":"document.js","sourcesContent":["import * as path from 'node:path';\r\nimport { spawn } from 'node:child_process';\r\nimport type { Context, ToolProgressEvent } from '@wrongstack/core';\r\n\r\nexport function resolvePath(input: string, ctx: Context): string {\r\n  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.cwd, input);\r\n}\r\n\r\nexport function ensureInsideRoot(absPath: string, ctx: Context): string {\r\n  const root = path.resolve(ctx.projectRoot);\r\n  const target = path.resolve(absPath);\r\n  const rel = path.relative(root, target);\r\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\r\n    throw new Error(`Path \"${absPath}\" is outside project root \"${root}\"`);\r\n  }\r\n  return target;\r\n}\r\n\r\nexport function safeResolve(input: string, ctx: Context): string {\r\n  return ensureInsideRoot(resolvePath(input, ctx), ctx);\r\n}\r\n\r\nexport function truncateMiddle(s: string, max: number): string {\r\n  if (Buffer.byteLength(s, 'utf8') <= max) return s;\r\n  const half = Math.floor(max / 2);\r\n  return (\r\n    s.slice(0, half) +\r\n    `\\n…[truncated ${Buffer.byteLength(s, 'utf8') - max} bytes from middle]…\\n` +\r\n    s.slice(-half)\r\n  );\r\n}\r\n\r\nexport function isBinaryBuffer(buf: Buffer): boolean {\r\n  const len = Math.min(buf.length, 8192);\r\n  for (let i = 0; i < len; i++) {\r\n    if (buf[i] === 0) return true;\r\n  }\r\n  return false;\r\n}\r\n\r\nexport interface SpawnStreamResult {\r\n  stdout: string;\r\n  stderr: string;\r\n  exitCode: number;\r\n  truncated: boolean;\r\n  error?: string;\r\n}\r\n\r\nexport interface SpawnStreamOptions {\r\n  cmd: string;\r\n  args: string[];\r\n  cwd: string;\r\n  signal: AbortSignal;\r\n  maxBytes?: number;\r\n  /** Bytes of new stdout/stderr to accumulate before yielding a `partial_output` event. */\r\n  flushBytes?: number;\r\n}\r\n\r\n/**\r\n * Spawn a child process and yield `partial_output` progress events as\r\n * stdout/stderr arrive (batched by byte threshold), then return the full\r\n * buffered result. Shared between install/lint/format/typecheck/test/audit\r\n * so the TUI live tail sees consistent progress regardless of which tool\r\n * is running.\r\n */\r\nexport async function* spawnStream(\r\n  opts: SpawnStreamOptions,\r\n): AsyncGenerator<ToolProgressEvent, SpawnStreamResult> {\r\n  const max = opts.maxBytes ?? 200_000;\r\n  const flushAt = opts.flushBytes ?? 4 * 1024;\r\n  let stdout = '';\r\n  let stderr = '';\r\n  let pending = '';\r\n  let error: string | undefined;\r\n\r\n  const child = spawn(opts.cmd, opts.args, {\r\n    cwd: opts.cwd,\r\n    signal: opts.signal,\r\n    stdio: ['ignore', 'pipe', 'pipe'],\r\n  });\r\n\r\n  type Chunk = { kind: 'out' | 'err' | 'close' | 'error'; data: string; code?: number };\r\n  const queue: Chunk[] = [];\r\n  let waiter: (() => void) | undefined;\r\n  const wake = () => {\r\n    if (waiter) {\r\n      const w = waiter;\r\n      waiter = undefined;\r\n      w();\r\n    }\r\n  };\r\n\r\n  child.stdout?.on('data', (c) => {\r\n    const s = c.toString();\r\n    if (stdout.length < max) stdout += s;\r\n    queue.push({ kind: 'out', data: s });\r\n    wake();\r\n  });\r\n  child.stderr?.on('data', (c) => {\r\n    const s = c.toString();\r\n    if (stderr.length < max) stderr += s;\r\n    queue.push({ kind: 'err', data: s });\r\n    wake();\r\n  });\r\n  child.on('error', (e) => {\r\n    error = e.message;\r\n    queue.push({ kind: 'error', data: e.message });\r\n    wake();\r\n  });\r\n  child.on('close', (code) => {\r\n    queue.push({ kind: 'close', data: '', code: code ?? 0 });\r\n    wake();\r\n  });\r\n\r\n  let exitCode = 0;\r\n  let spawnFailed = false;\r\n  for (;;) {\r\n    while (queue.length === 0) {\r\n      await new Promise<void>((resolve) => {\r\n        waiter = resolve;\r\n      });\r\n    }\r\n    const chunk = queue.shift()!;\r\n    if (chunk.kind === 'close') {\r\n      // If we already saw a spawn error (ENOENT etc.), keep exitCode=1\r\n      // rather than the negative platform code Node fabricates.\r\n      if (!spawnFailed) exitCode = chunk.code ?? 0;\r\n      break;\r\n    }\r\n    if (chunk.kind === 'error') {\r\n      spawnFailed = true;\r\n      exitCode = 1;\r\n      // close usually follows\r\n      continue;\r\n    }\r\n    pending += chunk.data;\r\n    if (pending.length >= flushAt) {\r\n      yield { type: 'partial_output', text: pending };\r\n      pending = '';\r\n    }\r\n  }\r\n  if (pending.length > 0) {\r\n    yield { type: 'partial_output', text: pending };\r\n  }\r\n\r\n  return {\r\n    stdout,\r\n    stderr,\r\n    exitCode,\r\n    truncated: stdout.length >= max || stderr.length >= max,\r\n    error,\r\n  };\r\n}\r\n","import * as fs from 'node:fs/promises';\r\nimport type { Tool } from '@wrongstack/core';\r\nimport { safeResolve } from './_util.js';\r\n\r\ninterface DocumentInput {\r\n  target: 'file' | 'function' | 'class' | 'type' | 'all';\r\n  path?: string;\r\n  files?: string | string[];\r\n  style?: 'jsdoc' | 'tsdoc' | 'block';\r\n  overwrite?: boolean;\r\n  cwd?: string;\r\n}\r\n\r\ninterface DocumentedItem {\r\n  path: string;\r\n  name: string;\r\n  signature: string;\r\n  docstring: string;\r\n  status: 'documented' | 'skipped' | 'error';\r\n  error?: string;\r\n}\r\n\r\ninterface DocumentOutput {\r\n  files_processed: number;\r\n  items_documented: number;\r\n  results: DocumentedItem[];\r\n  style: string;\r\n}\r\n\r\nconst JSDOC_TEMPLATE = `/**\r\n * {description}\r\n *{params}\r\n * @returns {returns}\r\n */`;\r\n\r\nconst BLOCK_TEMPLATE = `/*\r\n * {description}\r\n *{params}\r\n * @returns {returns}\r\n */`;\r\n\r\nexport const documentTool: Tool<DocumentInput, DocumentOutput> = {\r\n  name: 'document',\r\n  description:\r\n    'Generate or update documentation comments for functions, classes, and types. Supports JSDoc, TSDoc, and block comments.',\r\n  usageHint:\r\n    'Set `target` for what to document. `files` for paths. `style` for comment format. `overwrite` replaces existing docs.',\r\n  permission: 'confirm',\r\n  mutating: true,\r\n  timeoutMs: 30_000,\r\n  inputSchema: {\r\n    type: 'object',\r\n    properties: {\r\n      target: {\r\n        type: 'string',\r\n        enum: ['file', 'function', 'class', 'type', 'all'],\r\n        description: 'What to document',\r\n      },\r\n      path: {\r\n        type: 'string',\r\n        description: 'Specific file path to document',\r\n      },\r\n      files: {\r\n        type: 'string',\r\n        description: 'File(s) to process: single path, comma-separated list, or glob',\r\n      },\r\n      style: {\r\n        type: 'string',\r\n        enum: ['jsdoc', 'tsdoc', 'block'],\r\n        description: 'Documentation style (default: jsdoc)',\r\n      },\r\n      overwrite: {\r\n        type: 'boolean',\r\n        description: 'Overwrite existing docstrings (default: false)',\r\n      },\r\n      cwd: { type: 'string', description: 'Working directory (default: cwd)' },\r\n    },\r\n  },\r\n  async execute(input, ctx) {\r\n    const cwd = input.cwd ? safeResolve(input.cwd, ctx) : ctx.cwd;\r\n    const style = input.style ?? 'jsdoc';\r\n    const results: DocumentedItem[] = [];\r\n    let filesProcessed = 0;\r\n    let itemsDocumented = 0;\r\n\r\n    const fileList = input.files\r\n      ? await resolveFiles(Array.isArray(input.files) ? input.files.join(',') : input.files, cwd)\r\n      : input.path\r\n        ? [safeResolve(input.path, ctx)]\r\n        : [];\r\n\r\n    for (const absPath of fileList) {\r\n      try {\r\n        const content = await fs.readFile(absPath, 'utf8');\r\n        filesProcessed++;\r\n        const processed = processFile(content, absPath, style, input.overwrite ?? false, input.target ?? 'all');\r\n        results.push(...processed);\r\n        itemsDocumented += processed.filter((r) => r.status === 'documented').length;\r\n      } catch (e) {\r\n        results.push({\r\n          path: absPath,\r\n          name: absPath.split('/').pop() ?? absPath,\r\n          signature: '',\r\n          docstring: '',\r\n          status: 'error',\r\n          error: e instanceof Error ? e.message : String(e),\r\n        });\r\n      }\r\n    }\r\n\r\n    return {\r\n      files_processed: filesProcessed,\r\n      items_documented: itemsDocumented,\r\n      results,\r\n      style,\r\n    };\r\n  },\r\n};\r\n\r\nasync function resolveFiles(filesInput: string, cwd: string): Promise<string[]> {\r\n  const files = Array.isArray(filesInput) ? filesInput : filesInput.split(',');\r\n  const resolved: string[] = [];\r\n\r\n  for (const f of files) {\r\n    const absPath = f.trim().startsWith('/') ? f.trim() : `${cwd}/${f.trim()}`;\r\n    try {\r\n      const stat = await fs.stat(absPath);\r\n      if (stat.isFile()) resolved.push(absPath);\r\n    } catch {\r\n      // skip\r\n    }\r\n  }\r\n\r\n  return resolved;\r\n}\r\n\r\nfunction processFile(\r\n  content: string,\r\n  absPath: string,\r\n  style: string,\r\n  overwrite: boolean,\r\n  target: string,\r\n): DocumentedItem[] {\r\n  const results: DocumentedItem[] = [];\r\n  const lines = content.split('\\n');\r\n  const functionRegex = /(?:async\\s+)?function\\s+(\\w+)\\s*\\(([^)]*)\\)/g;\r\n  const arrowRegex = /(?:const|let|var)\\s+(\\w+)\\s*=\\s*(?:async\\s+)?\\(([^)]*)\\)\\s*=>/g;\r\n  const classRegex = /class\\s+(\\w+)/g;\r\n  const typeRegex = /(?:type|interface)\\s+(\\w+)\\s*[=<]/g;\r\n\r\n  const allMatches: { name: string; sig: string; type: string; line: number }[] = [];\r\n\r\n  if (target === 'all' || target === 'function') {\r\n    for (const m of content.matchAll(functionRegex)) {\r\n      if (!m[1]) continue;\r\n      allMatches.push({ name: m[1], sig: m[2] ?? '', type: 'function', line: content.slice(0, m.index).split('\\n').length });\r\n    }\r\n    for (const m of content.matchAll(arrowRegex)) {\r\n      if (!m[1]) continue;\r\n      allMatches.push({ name: m[1], sig: m[2] ?? '', type: 'arrow', line: content.slice(0, m.index).split('\\n').length });\r\n    }\r\n  }\r\n\r\n  if (target === 'all' || target === 'class') {\r\n    for (const m of content.matchAll(classRegex)) {\r\n      if (!m[1]) continue;\r\n      allMatches.push({ name: m[1], sig: '', type: 'class', line: content.slice(0, m.index).split('\\n').length });\r\n    }\r\n  }\r\n\r\n  if (target === 'all' || target === 'type') {\r\n    for (const m of content.matchAll(typeRegex)) {\r\n      if (!m[1]) continue;\r\n      allMatches.push({ name: m[1], sig: m[0] ?? '', type: 'type', line: content.slice(0, m.index).split('\\n').length });\r\n    }\r\n  }\r\n\r\n  for (const m of allMatches) {\r\n    results.push({\r\n      path: absPath,\r\n      name: m.name,\r\n      signature: m.sig,\r\n      docstring: `/** ${m.name} - documented at line ${m.line} */`,\r\n      status: 'skipped',\r\n    });\r\n  }\r\n\r\n  return results;\r\n}"]}

package/dist/edit.d.ts

@@ -0,0 +1,22 @@
+import { Tool } from '@wrongstack/core';
+
+interface EditInput {
+    path: string;
+    old_string: string;
+    new_string: string;
+    /**
+     * When true, replaces all occurrences of `old_string`.
+     * When false (default), replaces only the first occurrence and errors
+     * if more than one match exists — use this to ensure you target the
+     * right location.
+     */
+    replace_all?: boolean;
+}
+interface EditOutput {
+    path: string;
+    replacements: number;
+    diff: string;
+}
+declare const editTool: Tool<EditInput, EditOutput>;
+
+export { editTool };

package/dist/edit.js

@@ -0,0 +1,138 @@
+import * as fs from 'fs/promises';
+import { detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff } from '@wrongstack/core';
+import * as path from 'path';
+import 'child_process';
+
+// src/edit.ts
+function resolvePath(input, ctx) {
+  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.cwd, input);
+}
+function ensureInsideRoot(absPath, ctx) {
+  const root = path.resolve(ctx.projectRoot);
+  const target = path.resolve(absPath);
+  const rel = path.relative(root, target);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`Path "${absPath}" is outside project root "${root}"`);
+  }
+  return target;
+}
+function safeResolve(input, ctx) {
+  return ensureInsideRoot(resolvePath(input, ctx), ctx);
+}
+
+// src/edit.ts
+var editTool = {
+  name: "edit",
+  description: "Make a surgical edit by replacing exact text. Fails if `old_string` is not unique unless `replace_all` is true.",
+  usageHint: "Always `read` the file first. `old_string` must be an EXACT match (whitespace included). If multiple matches exist, either narrow `old_string` with more context or set `replace_all: true`.",
+  permission: "confirm",
+  mutating: true,
+  timeoutMs: 5e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: { type: "string" },
+      old_string: { type: "string" },
+      new_string: { type: "string" },
+      replace_all: { type: "boolean" }
+    },
+    required: ["path", "old_string", "new_string"]
+  },
+  async execute(input, ctx) {
+    if (!input?.path) throw new Error("edit: path is required");
+    if (input.old_string === void 0) throw new Error("edit: old_string is required");
+    if (input.new_string === void 0) throw new Error("edit: new_string is required");
+    if (input.old_string === "") throw new Error("edit: old_string cannot be empty");
+    const absPath = safeResolve(input.path, ctx);
+    const stat2 = await fs.stat(absPath).catch((err) => {
+      if (err.code === "ENOENT") {
+        throw new Error(`edit: file "${input.path}" does not exist. Use \`write\` instead.`);
+      }
+      throw err;
+    });
+    if (!stat2.isFile()) throw new Error(`edit: "${input.path}" is not a regular file`);
+    if (!ctx.hasRead(absPath)) {
+      throw new Error(
+        `edit: file "${input.path}" was not read in this session. Read it first.`
+      );
+    }
+    const lastReadMtime = ctx.lastReadMtime(absPath);
+    if (lastReadMtime !== void 0 && stat2.mtimeMs > lastReadMtime + 1) {
+      throw new Error(`edit: file "${input.path}" was modified externally. Re-read it first.`);
+    }
+    const original = await fs.readFile(absPath, "utf8");
+    const style = detectNewlineStyle(original);
+    const fileLf = normalizeToLf(original);
+    const oldLf = normalizeToLf(input.old_string);
+    const newLf = normalizeToLf(input.new_string);
+    if (oldLf === newLf) {
+      return {
+        path: absPath,
+        replacements: 0,
+        diff: "(no-op: old and new are identical)"
+      };
+    }
+    let count = 0;
+    let idx = fileLf.indexOf(oldLf);
+    const matches = [];
+    while (idx !== -1) {
+      matches.push(idx);
+      count++;
+      idx = fileLf.indexOf(oldLf, idx + 1);
+    }
+    if (count === 0) {
+      const hint = findSimilarity(fileLf, oldLf);
+      throw new Error(
+        `edit: no match for old_string in "${input.path}".${hint ? ` Nearest match near line ${hint}.` : ""}`
+      );
+    }
+    if (count > 1 && !input.replace_all) {
+      const lines = lineNumbersFor(fileLf, matches);
+      throw new Error(
+        `edit: old_string matched ${count} times in "${input.path}" (lines: ${lines.join(", ")}). Add more context to make it unique, or set replace_all: true.`
+      );
+    }
+    const newFileLf = input.replace_all ? fileLf.split(oldLf).join(newLf) : fileLf.replace(oldLf, newLf);
+    const newFile = toStyle(newFileLf, style);
+    await atomicWrite(absPath, newFile, { mode: stat2.mode & 511 });
+    const updated = await fs.stat(absPath);
+    ctx.recordRead(absPath, updated.mtimeMs);
+    const diff = unifiedDiff(original, newFile, {
+      fromFile: input.path,
+      toFile: input.path
+    });
+    return {
+      path: absPath,
+      replacements: input.replace_all ? count : 1,
+      diff
+    };
+  }
+};
+function lineNumbersFor(text, indices) {
+  const out = [];
+  let pos = 0;
+  let line = 1;
+  for (const target of indices) {
+    while (pos < target) {
+      if (text.charCodeAt(pos) === 10) line++;
+      pos++;
+    }
+    out.push(line);
+  }
+  return out;
+}
+function findSimilarity(haystack, needle) {
+  if (needle.length < 20) return void 0;
+  const probe = needle.slice(0, Math.min(40, needle.length));
+  const idx = haystack.indexOf(probe);
+  if (idx === -1) return void 0;
+  let line = 1;
+  for (let i = 0; i < idx; i++) {
+    if (haystack.charCodeAt(i) === 10) line++;
+  }
+  return line;
+}
+
+export { editTool };
+//# sourceMappingURL=edit.js.map
+//# sourceMappingURL=edit.js.map

package/dist/edit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/_util.ts","../src/edit.ts"],"names":["stat"],"mappings":"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","file":"edit.js","sourcesContent":["import * as path from 'node:path';\r\nimport { spawn } from 'node:child_process';\r\nimport type { Context, ToolProgressEvent } from '@wrongstack/core';\r\n\r\nexport function resolvePath(input: string, ctx: Context): string {\r\n  return path.isAbsolute(input) ? path.normalize(input) : path.resolve(ctx.cwd, input);\r\n}\r\n\r\nexport function ensureInsideRoot(absPath: string, ctx: Context): string {\r\n  const root = path.resolve(ctx.projectRoot);\r\n  const target = path.resolve(absPath);\r\n  const rel = path.relative(root, target);\r\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\r\n    throw new Error(`Path \"${absPath}\" is outside project root \"${root}\"`);\r\n  }\r\n  return target;\r\n}\r\n\r\nexport function safeResolve(input: string, ctx: Context): string {\r\n  return ensureInsideRoot(resolvePath(input, ctx), ctx);\r\n}\r\n\r\nexport function truncateMiddle(s: string, max: number): string {\r\n  if (Buffer.byteLength(s, 'utf8') <= max) return s;\r\n  const half = Math.floor(max / 2);\r\n  return (\r\n    s.slice(0, half) +\r\n    `\\n…[truncated ${Buffer.byteLength(s, 'utf8') - max} bytes from middle]…\\n` +\r\n    s.slice(-half)\r\n  );\r\n}\r\n\r\nexport function isBinaryBuffer(buf: Buffer): boolean {\r\n  const len = Math.min(buf.length, 8192);\r\n  for (let i = 0; i < len; i++) {\r\n    if (buf[i] === 0) return true;\r\n  }\r\n  return false;\r\n}\r\n\r\nexport interface SpawnStreamResult {\r\n  stdout: string;\r\n  stderr: string;\r\n  exitCode: number;\r\n  truncated: boolean;\r\n  error?: string;\r\n}\r\n\r\nexport interface SpawnStreamOptions {\r\n  cmd: string;\r\n  args: string[];\r\n  cwd: string;\r\n  signal: AbortSignal;\r\n  maxBytes?: number;\r\n  /** Bytes of new stdout/stderr to accumulate before yielding a `partial_output` event. */\r\n  flushBytes?: number;\r\n}\r\n\r\n/**\r\n * Spawn a child process and yield `partial_output` progress events as\r\n * stdout/stderr arrive (batched by byte threshold), then return the full\r\n * buffered result. Shared between install/lint/format/typecheck/test/audit\r\n * so the TUI live tail sees consistent progress regardless of which tool\r\n * is running.\r\n */\r\nexport async function* spawnStream(\r\n  opts: SpawnStreamOptions,\r\n): AsyncGenerator<ToolProgressEvent, SpawnStreamResult> {\r\n  const max = opts.maxBytes ?? 200_000;\r\n  const flushAt = opts.flushBytes ?? 4 * 1024;\r\n  let stdout = '';\r\n  let stderr = '';\r\n  let pending = '';\r\n  let error: string | undefined;\r\n\r\n  const child = spawn(opts.cmd, opts.args, {\r\n    cwd: opts.cwd,\r\n    signal: opts.signal,\r\n    stdio: ['ignore', 'pipe', 'pipe'],\r\n  });\r\n\r\n  type Chunk = { kind: 'out' | 'err' | 'close' | 'error'; data: string; code?: number };\r\n  const queue: Chunk[] = [];\r\n  let waiter: (() => void) | undefined;\r\n  const wake = () => {\r\n    if (waiter) {\r\n      const w = waiter;\r\n      waiter = undefined;\r\n      w();\r\n    }\r\n  };\r\n\r\n  child.stdout?.on('data', (c) => {\r\n    const s = c.toString();\r\n    if (stdout.length < max) stdout += s;\r\n    queue.push({ kind: 'out', data: s });\r\n    wake();\r\n  });\r\n  child.stderr?.on('data', (c) => {\r\n    const s = c.toString();\r\n    if (stderr.length < max) stderr += s;\r\n    queue.push({ kind: 'err', data: s });\r\n    wake();\r\n  });\r\n  child.on('error', (e) => {\r\n    error = e.message;\r\n    queue.push({ kind: 'error', data: e.message });\r\n    wake();\r\n  });\r\n  child.on('close', (code) => {\r\n    queue.push({ kind: 'close', data: '', code: code ?? 0 });\r\n    wake();\r\n  });\r\n\r\n  let exitCode = 0;\r\n  let spawnFailed = false;\r\n  for (;;) {\r\n    while (queue.length === 0) {\r\n      await new Promise<void>((resolve) => {\r\n        waiter = resolve;\r\n      });\r\n    }\r\n    const chunk = queue.shift()!;\r\n    if (chunk.kind === 'close') {\r\n      // If we already saw a spawn error (ENOENT etc.), keep exitCode=1\r\n      // rather than the negative platform code Node fabricates.\r\n      if (!spawnFailed) exitCode = chunk.code ?? 0;\r\n      break;\r\n    }\r\n    if (chunk.kind === 'error') {\r\n      spawnFailed = true;\r\n      exitCode = 1;\r\n      // close usually follows\r\n      continue;\r\n    }\r\n    pending += chunk.data;\r\n    if (pending.length >= flushAt) {\r\n      yield { type: 'partial_output', text: pending };\r\n      pending = '';\r\n    }\r\n  }\r\n  if (pending.length > 0) {\r\n    yield { type: 'partial_output', text: pending };\r\n  }\r\n\r\n  return {\r\n    stdout,\r\n    stderr,\r\n    exitCode,\r\n    truncated: stdout.length >= max || stderr.length >= max,\r\n    error,\r\n  };\r\n}\r\n","import * as fs from 'node:fs/promises';\nimport {\n  atomicWrite,\n  detectNewlineStyle,\n  toStyle,\n  normalizeToLf,\n  unifiedDiff,\n} from '@wrongstack/core';\nimport type { Tool } from '@wrongstack/core';\nimport { safeResolve } from './_util.js';\n\ninterface EditInput {\n  path: string;\n  old_string: string;\n  new_string: string;\n  /**\n   * When true, replaces all occurrences of `old_string`.\n   * When false (default), replaces only the first occurrence and errors\n   * if more than one match exists — use this to ensure you target the\n   * right location.\n   */\n  replace_all?: boolean;\n}\n\ninterface EditOutput {\n  path: string;\n  replacements: number;\n  diff: string;\n}\n\nexport const editTool: Tool<EditInput, EditOutput> = {\n  name: 'edit',\n  description:\n    'Make a surgical edit by replacing exact text. Fails if `old_string` is not unique unless `replace_all` is true.',\n  usageHint:\n    'Always `read` the file first. `old_string` must be an EXACT match (whitespace included). If multiple matches exist, either narrow `old_string` with more context or set `replace_all: true`.',\n  permission: 'confirm',\n  mutating: true,\n  timeoutMs: 5_000,\n  inputSchema: {\n    type: 'object',\n    properties: {\n      path: { type: 'string' },\n      old_string: { type: 'string' },\n      new_string: { type: 'string' },\n      replace_all: { type: 'boolean' },\n    },\n    required: ['path', 'old_string', 'new_string'],\n  },\n  async execute(input, ctx) {\n    if (!input?.path) throw new Error('edit: path is required');\n    if (input.old_string === undefined) throw new Error('edit: old_string is required');\n    if (input.new_string === undefined) throw new Error('edit: new_string is required');\n    if (input.old_string === '') throw new Error('edit: old_string cannot be empty');\n\n    const absPath = safeResolve(input.path, ctx);\n    const stat = await fs.stat(absPath).catch((err) => {\n      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n        throw new Error(`edit: file \"${input.path}\" does not exist. Use \\`write\\` instead.`);\n      }\n      throw err;\n    });\n    if (!stat.isFile()) throw new Error(`edit: \"${input.path}\" is not a regular file`);\n\n    // Read-before-write invariant\n    if (!ctx.hasRead(absPath)) {\n      throw new Error(\n        `edit: file \"${input.path}\" was not read in this session. Read it first.`,\n      );\n    }\n    // Stale-read detection\n    const lastReadMtime = ctx.lastReadMtime(absPath);\n    if (lastReadMtime !== undefined && stat.mtimeMs > lastReadMtime + 1) {\n      throw new Error(`edit: file \"${input.path}\" was modified externally. Re-read it first.`);\n    }\n\n    const original = await fs.readFile(absPath, 'utf8');\n    const style = detectNewlineStyle(original);\n    const fileLf = normalizeToLf(original);\n    const oldLf = normalizeToLf(input.old_string);\n    const newLf = normalizeToLf(input.new_string);\n\n    if (oldLf === newLf) {\n      return {\n        path: absPath,\n        replacements: 0,\n        diff: '(no-op: old and new are identical)',\n      };\n    }\n\n    let count = 0;\n    let idx = fileLf.indexOf(oldLf);\n    const matches: number[] = [];\n    while (idx !== -1) {\n      matches.push(idx);\n      count++;\n      idx = fileLf.indexOf(oldLf, idx + 1);\n    }\n\n    if (count === 0) {\n      const hint = findSimilarity(fileLf, oldLf);\n      throw new Error(\n        `edit: no match for old_string in \"${input.path}\".${\n          hint ? ` Nearest match near line ${hint}.` : ''\n        }`,\n      );\n    }\n\n    if (count > 1 && !input.replace_all) {\n      const lines = lineNumbersFor(fileLf, matches);\n      throw new Error(\n        `edit: old_string matched ${count} times in \"${input.path}\" (lines: ${lines.join(', ')}). ` +\n          `Add more context to make it unique, or set replace_all: true.`,\n      );\n    }\n\n    const newFileLf = input.replace_all\n      ? fileLf.split(oldLf).join(newLf)\n      : fileLf.replace(oldLf, newLf);\n    const newFile = toStyle(newFileLf, style);\n\n    await atomicWrite(absPath, newFile, { mode: stat.mode & 0o777 });\n    const updated = await fs.stat(absPath);\n    ctx.recordRead(absPath, updated.mtimeMs);\n\n    const diff = unifiedDiff(original, newFile, {\n      fromFile: input.path,\n      toFile: input.path,\n    });\n\n    return {\n      path: absPath,\n      replacements: input.replace_all ? count : 1,\n      diff,\n    };\n  },\n};\n\nfunction lineNumbersFor(text: string, indices: number[]): number[] {\n  const out: number[] = [];\n  let pos = 0;\n  let line = 1;\n  for (const target of indices) {\n    while (pos < target) {\n      if (text.charCodeAt(pos) === 0x0a) line++;\n      pos++;\n    }\n    out.push(line);\n  }\n  return out;\n}\n\nfunction findSimilarity(haystack: string, needle: string): number | undefined {\n  if (needle.length < 20) return undefined;\n  const probe = needle.slice(0, Math.min(40, needle.length));\n  const idx = haystack.indexOf(probe);\n  if (idx === -1) return undefined;\n  let line = 1;\n  for (let i = 0; i < idx; i++) {\n    if (haystack.charCodeAt(i) === 0x0a) line++;\n  }\n  return line;\n}\n"]}

package/dist/exec.d.ts

@@ -0,0 +1,21 @@
+import { Tool } from '@wrongstack/core';
+
+interface ExecInput {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    timeout?: number;
+    allow_unknown?: boolean;
+}
+interface ExecOutput {
+    command: string;
+    args: string[];
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    truncated: boolean;
+    allowed: boolean;
+}
+declare const execTool: Tool<ExecInput, ExecOutput>;
+
+export { execTool };