@wrongstack/tools 0.1.10 → 0.3.1

package/dist/builtin.js

@@ -1,5 +1,5 @@
 import { spawn } from 'child_process';
-import { buildChildEnv, stripAnsi, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, compileGlob } from '@wrongstack/core';
+import { buildChildEnv, stripAnsi, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, compileGlob, loadPlan, emptyPlan, clearPlan, savePlan, removePlanItem, setPlanItemStatus, addPlanItem, formatPlan } from '@wrongstack/core';
 import * as path from 'path';
 import { dirname } from 'path';
 import * as os from 'os';
@@ -125,6 +125,7 @@ function isBinaryBuffer(buf) {
 // src/audit.ts
 var auditTool = {
   name: "audit",
+  category: "Package Management",
   description: "Run npm/pnpm security audit. Returns vulnerabilities sorted by severity.",
   usageHint: "Set `level` to filter minimum severity. `fix` attempts auto-fix. `packages` checks specific packages.",
   permission: "confirm",
@@ -238,6 +239,7 @@ var STREAM_FLUSH_INTERVAL_MS = 200;
 var STREAM_FLUSH_BYTES = 4 * 1024;
 var bashTool = {
   name: "bash",
+  category: "Shell",
   description: "Run a shell command. stdout and stderr are merged.",
   usageHint: "Runs via `bash -c` (or `cmd /c` on Windows). Cwd is the project root. Default timeout 30s. Output truncated from the middle if oversized. Use for git, npm, builds, tests.",
   permission: "confirm",
@@ -417,10 +419,11 @@ var bashTool = {
 // src/batch-tool-use.ts
 var batchToolUseTool = {
   name: "batch_tool_use",
+  category: "Meta",
   description: "Execute multiple tool calls in sequence or parallel. Returns all results.",
   usageHint: "Set `calls` array with tool names and inputs. `stop_on_error` halts on first failure. `parallel` runs concurrently (default: true).",
   permission: "confirm",
-  mutating: false,
+  mutating: true,
   timeoutMs: 12e4,
   inputSchema: {
     type: "object",
@@ -518,6 +521,7 @@ async function executeSingle(call, ctx, opts) {
 }
 var diffTool = {
   name: "diff",
+  category: "Filesystem",
   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",
@@ -634,6 +638,7 @@ function formatUnified(lines, context) {
 }
 var documentTool = {
   name: "document",
+  category: "Project",
   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",
@@ -782,6 +787,7 @@ function processFile(content, absPath, style, overwrite, target) {
 }
 var editTool = {
   name: "edit",
+  category: "Filesystem",
   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",
@@ -938,10 +944,11 @@ var MAX_OUTPUT2 = 2e5;
 var TIMEOUT_MS = 3e4;
 var execTool = {
   name: "exec",
+  category: "Shell",
   description: "Restricted shell that only runs pre-approved commands with constrained arguments. Safer alternative to `bash`.",
   usageHint: "Set `command` (must be in allowlist). `args` passed through. For arbitrary shell access use the `bash` tool instead.",
   permission: "confirm",
-  mutating: false,
+  mutating: true,
   timeoutMs: TIMEOUT_MS,
   inputSchema: {
     type: "object",
@@ -1083,6 +1090,7 @@ async function fetchWithRedirectLimit(url, maxRedirects, signal) {
 }
 var fetchTool = {
   name: "fetch",
+  category: "Network",
   description: "Fetch the contents of a URL. HTML is converted to markdown by default.",
   usageHint: "HTTPS only by default. Localhost and RFC1918 ranges blocked unless WRONGSTACK_FETCH_ALLOW_PRIVATE=1. Max 5 redirects, 20s timeout, 128KB cap.",
   permission: "confirm",
@@ -1331,6 +1339,7 @@ function stripTags(s) {
 // src/format.ts
 var formatTool = {
   name: "format",
+  category: "Code Quality",
   description: "Format files with biome or prettier. Use `check` to verify without modifying.",
   usageHint: "Set `files` (glob or comma-separated). `check` only validates. `fixer` forces tool.",
   permission: "confirm",
@@ -1429,6 +1438,7 @@ var TIMEOUT_MS3 = 3e4;
 var MAX_OUTPUT3 = 1e5;
 var gitTool = {
   name: "git",
+  category: "Git",
   description: "Run git commands. Wraps common operations: status, log, diff, commit, branch, checkout, stash, push, pull, fetch, reset.",
   usageHint: "Prefer built-in subcommands over raw args. `command` is required. `message` for commits. `branch` for checkout/branch. `files` for status/diff. `format` for log.",
   permission: "confirm",
@@ -1593,6 +1603,7 @@ function runGit2(args, cwd, signal) {
 var DEFAULT_IGNORE = ["node_modules", ".git", "dist", "build", ".next", "coverage", ".turbo"];
 var globTool = {
   name: "glob",
+  category: "Filesystem",
   description: "Find files matching a glob pattern. Returns paths sorted by mtime (newest first).",
   usageHint: "Examples: `**/*.ts`, `src/**/*.test.ts`, `*.json`. Common dirs (node_modules, .git, dist) are ignored by default. Returns up to 1000 paths.",
   permission: "auto",
@@ -1709,6 +1720,7 @@ function capSubject(line) {
 var DEFAULT_IGNORE2 = ["node_modules", ".git", "dist", "build", ".next", "coverage"];
 var grepTool = {
   name: "grep",
+  category: "Search",
   description: "Search file contents with a regex. Uses ripgrep when available.",
   usageHint: 'Pattern is regex. Use `output_mode: "content"` for matched lines, `"files_with_matches"` for paths, `"count"` for tallies. `glob` filters files (e.g. `*.ts`).',
   permission: "auto",
@@ -1741,6 +1753,10 @@ var grepTool = {
     const base = input.path ? safeResolve(input.path, ctx) : ctx.cwd;
     const mode = input.output_mode ?? "content";
     const limit = Math.max(1, Math.min(input.limit ?? 200, 2e3));
+    const validation = compileUserRegex(input.pattern, input.case_insensitive ? "i" : "");
+    if (!validation.ok) {
+      throw new Error(`grep: ${validation.reason}`);
+    }
     const rgAvailable = await detectRg(opts.signal);
     if (rgAvailable) {
       try {
@@ -1774,11 +1790,15 @@ async function* runRgStream(input, base, mode, limit, signal) {
     args.push("-n");
     if (input.context_lines) args.push("-C", String(input.context_lines));
   }
+  for (const ignored of DEFAULT_IGNORE2) {
+    args.push("--glob", `!${ignored}/**`, "--glob", `!**/${ignored}/**`);
+  }
   if (input.glob) args.push("--glob", input.glob);
   args.push("--", input.pattern, base);
   const matches = [];
   let buf = "";
   let totalLines = 0;
+  let totalCount = 0;
   let batchSinceFlush = 0;
   const FLUSH_AT = 16;
   const MAX_BUF_BYTES = 1e6;
@@ -1835,6 +1855,7 @@ async function* runRgStream(input, base, mode, limit, signal) {
     for (const line of ready.split("\n")) {
       if (!line) continue;
       totalLines++;
+      if (mode === "count") totalCount += parseRgCountLine(line);
       if (matches.length < limit) {
         matches.push(line);
         pendingBatch.push(line);
@@ -1855,6 +1876,7 @@ async function* runRgStream(input, base, mode, limit, signal) {
     for (const line of buf.split("\n")) {
       if (!line) continue;
       totalLines++;
+      if (mode === "count") totalCount += parseRgCountLine(line);
       if (matches.length < limit) {
         matches.push(line);
         pendingBatch.push(line);
@@ -1873,12 +1895,18 @@ async function* runRgStream(input, base, mode, limit, signal) {
     type: "final",
     output: {
       matches,
-      count: totalLines,
+      count: mode === "count" ? totalCount : totalLines,
       truncated: totalLines > limit || bufOverflow,
       used: "rg"
     }
   };
 }
+function parseRgCountLine(line) {
+  const idx = line.lastIndexOf(":");
+  if (idx === -1) return 0;
+  const n = Number.parseInt(line.slice(idx + 1), 10);
+  return Number.isFinite(n) ? n : 0;
+}
 async function runNative(input, base, mode, limit, signal) {
   const flags = input.case_insensitive ? "i" : "";
   const compiled = compileUserRegex(input.pattern, flags);
@@ -1955,6 +1983,7 @@ async function runNative(input, base, mode, limit, signal) {
 // src/install.ts
 var installTool = {
   name: "install",
+  category: "Package Management",
   description: "Install npm packages. Detects pnpm/npm/yarn and uses the right package manager.",
   usageHint: "Set `packages` to install. `save` as dependency type. `global` for global install. `dry_run` to preview.",
   permission: "confirm",
@@ -2048,6 +2077,7 @@ async function detectPackageManager(cwd) {
 }
 var jsonTool = {
   name: "json",
+  category: "Data",
   description: "Parse, query, and validate JSON/JSON5/YAML. Use `query` with JMESPath-like paths to extract values.",
   usageHint: 'Provide `file` path or `data` string. `query` supports dot notation (e.g. "results[0].name"). `format` outputs in specified format.',
   permission: "auto",
@@ -2170,6 +2200,7 @@ function toYaml(data, indent = 0) {
 // src/lint.ts
 var lintTool = {
   name: "lint",
+  category: "Code Quality",
   description: "Run a linter on files. Auto-detects biome, eslint, or tslint. Use `fix` to auto-fix issues.",
   usageHint: "Set `files` (glob or comma-separated). `fix` applies corrections. `linter` forces specific tool.",
   permission: "confirm",
@@ -2259,6 +2290,7 @@ async function detectLinter(cwd) {
 }
 var logsTool = {
   name: "logs",
+  category: "Logs",
   description: "Stream or fetch logs from a service or file. Supports Docker, systemd, or plain log files.",
   usageHint: "Set `service` for Docker/systemd, `path` for file. `lines` limits output. `stream` for tail -f behavior. `filter` regex filters lines.",
   permission: "confirm",
@@ -2436,6 +2468,7 @@ function parseLine(line) {
 }
 var outdatedTool = {
   name: "outdated",
+  category: "Package Management",
   description: "Check for outdated npm packages. Shows current, wanted, and latest versions.",
   usageHint: "Set `check` to filter specific packages. `format` as list or table. `include_deprecated` shows deprecated packages.",
   permission: "auto",
@@ -2547,6 +2580,7 @@ function parseOutdatedOutput(json, exitCode) {
 }
 var patchTool = {
   name: "patch",
+  category: "Filesystem",
   description: "Apply a unified diff patch to files. Writes .orig and .rej files on failure.",
   usageHint: "Set `patch` (the diff text). `directory` defaults to cwd. `strip` removes leading path components. `dry_run` previews.",
   permission: "confirm",
@@ -2653,9 +2687,108 @@ function extractPatchedFiles(output) {
   }
   return files;
 }
+var planTool = {
+  name: "plan",
+  category: "Session",
+  description: "Inspect or edit the strategic plan board for this session. Plans persist across resume (unlike todos). Use this to lay out the multi-step approach before diving in, then mark steps in_progress/done as the work proceeds.",
+  usageHint: "Set action to one of: show | add | start | done | remove | clear. Pass `title` for add. Pass `target` (item id, 1-based index, or title substring) for start/done/remove. Always returns the formatted plan plus open/total counts.",
+  permission: "auto",
+  mutating: false,
+  timeoutMs: 2e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["show", "add", "start", "done", "remove", "clear"]
+      },
+      title: { type: "string", description: "Required when action = add." },
+      details: { type: "string", description: "Optional extra context for add." },
+      target: {
+        type: "string",
+        description: "Plan item id, 1-based index, or title substring. Required for start/done/remove."
+      }
+    },
+    required: ["action"]
+  },
+  async execute(input, ctx) {
+    const planPath = ctx.meta["plan.path"];
+    if (typeof planPath !== "string" || !planPath) {
+      return {
+        ok: false,
+        message: "Plan storage path is not configured for this session.",
+        plan: "",
+        count: 0,
+        open: 0
+      };
+    }
+    const sessionId = ctx.session?.id ?? "unknown";
+    let plan = await loadPlan(planPath) ?? emptyPlan(sessionId);
+    switch (input.action) {
+      case "show":
+        break;
+      case "add": {
+        const title = input.title?.trim();
+        if (!title) {
+          return mkResult(plan, false, "add requires `title`.");
+        }
+        ({ plan } = addPlanItem(plan, title, input.details?.trim() || void 0));
+        await savePlan(planPath, plan);
+        break;
+      }
+      case "start":
+      case "done": {
+        if (!input.target) {
+          return mkResult(plan, false, `${input.action} requires \`target\` (id|index|substring).`);
+        }
+        const next = setPlanItemStatus(
+          plan,
+          input.target,
+          input.action === "start" ? "in_progress" : "done"
+        );
+        if (next === plan) {
+          return mkResult(plan, false, `No plan item matched "${input.target}".`);
+        }
+        plan = next;
+        await savePlan(planPath, plan);
+        break;
+      }
+      case "remove": {
+        if (!input.target) {
+          return mkResult(plan, false, "remove requires `target` (id|index|substring).");
+        }
+        const next = removePlanItem(plan, input.target);
+        if (next === plan) {
+          return mkResult(plan, false, `No plan item matched "${input.target}".`);
+        }
+        plan = next;
+        await savePlan(planPath, plan);
+        break;
+      }
+      case "clear":
+        plan = clearPlan(plan);
+        await savePlan(planPath, plan);
+        break;
+      default:
+        return mkResult(plan, false, `Unknown action "${input.action}".`);
+    }
+    return mkResult(plan, true, `Plan ${input.action} ok.`);
+  }
+};
+function mkResult(plan, ok, message) {
+  const open = plan.items.filter((i) => i.status !== "done").length;
+  return {
+    ok,
+    message,
+    plan: formatPlan(plan),
+    count: plan.items.length,
+    open
+  };
+}
 var MAX_BYTES2 = 5 * 1024 * 1024;
 var readTool = {
   name: "read",
+  category: "Filesystem",
   description: "Read the contents of a file. Lines are 1-indexed and prefixed with line numbers.",
   usageHint: "Read a file before editing it. Returns lines numbered like `   1\u2192content`. Use `offset` and `limit` for large files (default reads up to 2000 lines).",
   permission: "auto",
@@ -2708,6 +2841,7 @@ var readTool = {
 var DEFAULT_IGNORE3 = ["node_modules", ".git", "dist", "build", ".next", "coverage"];
 var replaceTool = {
   name: "replace",
+  category: "Transform",
   description: "Batch replace a pattern across multiple files matched by glob. Returns diff for each modified file.",
   usageHint: 'Use `glob` for broad patterns (e.g. "**/*.ts"). Set `dry_run: true` to preview without modifying. `files` can be a single path, comma-separated list, or glob pattern.',
   permission: "confirm",
@@ -2736,7 +2870,7 @@ var replaceTool = {
     if (input.replacement === void 0) throw new Error("replace: replacement is required");
     if (!input?.files) throw new Error("replace: files is required");
     const replaceAll = input.replace_all ?? true;
-    const compiled = compileUserRegex(input.pattern, replaceAll ? "g" : "");
+    const compiled = compileUserRegex(input.pattern, "g");
     if (!compiled.ok) {
       throw new Error(`replace: ${compiled.reason}`);
     }
@@ -2775,11 +2909,17 @@ var replaceTool = {
       const style = detectNewlineStyle(content);
       const contentLf = normalizeToLf(content);
       re.lastIndex = 0;
-      const matches = [...contentLf.matchAll(re)];
-      if (matches.length === 0) continue;
-      const newContentLf = contentLf.replace(re, input.replacement);
+      const allMatches = [...contentLf.matchAll(re)];
+      if (allMatches.length === 0) continue;
+      const matches = replaceAll ? allMatches : allMatches.slice(0, 1);
+      const count = matches.length;
+      let newContentLf = contentLf;
+      for (let i = matches.length - 1; i >= 0; i--) {
+        const m = matches[i];
+        newContentLf = newContentLf.slice(0, m.index) + input.replacement + newContentLf.slice(m.index + m[0].length);
+      }
       re.lastIndex = 0;
-      totalReplacements += matches.length;
+      totalReplacements += count;
       if (!dryRun) {
         const newContent = toStyle(newContentLf, style);
         await atomicWrite(realPath, newContent, { mode: stat9.mode & 511 });
@@ -2981,6 +3121,7 @@ describe('{{Name}}', () => {
 };
 var scaffoldTool = {
   name: "scaffold",
+  category: "Project",
   description: "Generate boilerplate code from built-in templates or paths. Creates package.json, source files, tests.",
   usageHint: "Set `template` (npm-package, cli-tool, react-component) and `name`. `vars` for template variables. `dry_run` preview.",
   permission: "confirm",
@@ -3069,6 +3210,7 @@ var MAX_RESULTS = 50;
 var TIMEOUT_MS4 = 15e3;
 var searchTool = {
   name: "search",
+  category: "Search",
   description: "Search the web for information. Returns title, URL, and snippet for each result.",
   usageHint: "Set `num_results` (1-50, default 10). Use `source` to pick engine: duckduckgo (default), google, bing.",
   permission: "confirm",
@@ -3277,6 +3419,7 @@ function stripTags2(html) {
 }
 var testTool = {
   name: "test",
+  category: "Code Quality",
   description: "Run tests with vitest, jest, or mocha. Returns pass/fail counts and output.",
   usageHint: "Set `files` for specific tests. `watch` enables watch mode. `coverage` generates coverage report. `grep` filters by name.",
   permission: "confirm",
@@ -3424,6 +3567,7 @@ function parseResult(runner, result, duration) {
 // src/todo.ts
 var todoTool = {
   name: "todo",
+  category: "Session",
   description: "Replace the current todo list with a new set of items.",
   usageHint: "Use for multi-step tasks. Replace the full list on each call. At most ONE task may be in_progress at a time. Items have id, content, status (pending|in_progress|completed), and optional activeForm.",
   permission: "auto",
@@ -3474,6 +3618,7 @@ var todoTool = {
 // src/tool-help.ts
 var toolHelpTool = {
   name: "tool_help",
+  category: "Meta",
   description: "Get help and usage information for a specific tool or list all available tools.",
   usageHint: "Set `tool` for specific help. Omit to list all tools. `format`: short (one-liner), full (schema), markdown (formatted).",
   permission: "auto",
@@ -3595,6 +3740,7 @@ function formatAllToolsMarkdown(tools) {
 // src/tool-search.ts
 var toolSearchTool = {
   name: "tool_search",
+  category: "Meta",
   description: "Search available tools by name, description, tags, permission level, or mutating flag.",
   usageHint: "Set `query` for keyword search. `tags` to filter by category. `permission` to filter by required permission. `mutating` to filter by mutating flag.",
   permission: "auto",
@@ -3662,10 +3808,11 @@ var toolSearchTool = {
 // src/tool-use.ts
 var toolUseTool = {
   name: "tool_use",
+  category: "Meta",
   description: "Execute a specific tool by name with given input. Useful when the agent knows exactly which tool to call.",
   usageHint: "Set `tool` with exact tool name and `input` with the tool parameters. Returns result or error.",
   permission: "confirm",
-  mutating: false,
+  mutating: true,
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -3737,6 +3884,7 @@ var DEFAULT_IGNORE4 = [
 ];
 var treeTool = {
   name: "tree",
+  category: "Filesystem",
   description: "Display directory structure as an ASCII tree. Shows files and folders with indentation.",
   usageHint: "Set `path` (default: cwd). `depth` limits nesting (default: 3). `glob` filters files. `exclude` ignores dirs. `show_files` toggles file listing (default: true).",
   permission: "auto",
@@ -3891,6 +4039,7 @@ async function walkDir(dir, depth, opts) {
 }
 var typecheckTool = {
   name: "typecheck",
+  category: "Code Quality",
   description: "Run TypeScript type checking with `tsc --noEmit`. Checks for type errors without compiling.",
   usageHint: "Set `project` for tsconfig path (default: nearest). `strict` enables strictest flags. `all` checks all projects in workspace.",
   permission: "confirm",
@@ -3970,6 +4119,7 @@ async function findTsConfig(cwd) {
 }
 var writeTool = {
   name: "write",
+  category: "Filesystem",
   description: "Write or overwrite a file. For existing files, prefer `edit` over `write`.",
   usageHint: "Use `write` for new files or full replacements. For partial edits use `edit`. Existing files must have been `read` first in this session.",
   permission: "confirm",
@@ -4032,6 +4182,7 @@ var builtinTools = [
   fetchTool,
   searchTool,
   todoTool,
+  planTool,
   gitTool,
   patchTool,
   jsonTool,