@wrongstack/tools 0.313.0 → 0.316.1

package/dist/chunk-RJZQWEMS.js

@@ -0,0 +1,84 @@
+// src/tool-search.ts
+var toolSearchTool = {
+  name: "tool_search",
+  category: "Meta",
+  description: "Search the catalog of available tools by name or description. Use this to discover which tool to use for a task. For the full schema and usage details of a specific tool, use `tool_help` instead.",
+  usageHint: "SELF-DISCOVERY TOOL:\n\n- Use when you need to find the right tool for a job.\n- `query` searches names and descriptions.\n- You can filter by `tags` (category), `permission`, or `mutating`.\n- Once you find the right tool name, use `tool_help` with that name for full schema details.\nCall this before guessing tool names. It helps you discover the best tool for the current situation.",
+  permission: "auto",
+  mutating: false,
+  timeoutMs: 1e3,
+  capabilities: ["tool.meta"],
+  icon: "meta",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search query for tool name or description"
+      },
+      tags: {
+        type: "array",
+        items: { type: "string" },
+        description: 'Filter by tags (e.g. "filesystem", "network", "dev")'
+      },
+      permission: {
+        type: "string",
+        enum: ["auto", "confirm", "deny"],
+        description: "Filter by required permission level"
+      },
+      mutating: {
+        type: "boolean",
+        description: "Filter by mutating flag (true=filters that modify, false=read-only)"
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum results to return (default: 20)",
+        minimum: 1,
+        maximum: 100
+      }
+    }
+  },
+  async execute(input, ctx) {
+    const limit = Math.min(input.limit ?? 20, 100);
+    const tools = ctx.catalogTools ?? ctx.tools;
+    const query = input.query?.toLowerCase() ?? "";
+    const filtered = tools.filter((t) => {
+      if (query && !t.name.toLowerCase().includes(query) && !t.description.toLowerCase().includes(query)) {
+        return false;
+      }
+      if (input.tags && input.tags.length > 0) {
+        const toolCat = (t.category ?? "").toLowerCase();
+        if (!input.tags.some((tag) => toolCat.includes(tag.toLowerCase()))) {
+          return false;
+        }
+      }
+      if (input.permission && t.permission !== input.permission) {
+        return false;
+      }
+      if (typeof input.mutating === "boolean" && t.mutating !== input.mutating) {
+        return false;
+      }
+      return true;
+    });
+    const results = filtered.slice(0, limit).map((t) => ({
+      name: t.name,
+      description: t.description,
+      permission: t.permission,
+      mutating: t.mutating
+    }));
+    const totalAvailable = tools.length;
+    const hint = results.length === 0 && query ? `No tools matched "${input.query}". Use tool-help (without arguments) to see all ${totalAvailable} available tools.` : void 0;
+    return {
+      tools: results,
+      total: filtered.length,
+      truncated: filtered.length > limit,
+      ...hint ? { hint } : {},
+      _available: totalAvailable
+    };
+  }
+};
+
+export {
+  toolSearchTool
+};
+//# sourceMappingURL=chunk-RJZQWEMS.js.map

package/dist/chunk-RXISBFR5.js

@@ -0,0 +1,315 @@
+import {
+  COMMAND_OUTPUT_MAX_BYTES,
+  normalizeCommandOutput
+} from "./chunk-D33S4RQG.js";
+
+// src/git.ts
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { assessCommitSafety } from "@wrongstack/core/coordination";
+import { buildChildEnv } from "@wrongstack/core/utils";
+var TIMEOUT_MS = 3e4;
+var MAX_OUTPUT = 1e5;
+var gitTool = {
+  name: "git",
+  category: "Git",
+  description: "Safe wrapper around common git operations. Supports status, log, diff, commit, branch, checkout, stash, push, pull, fetch, reset, worktree, etc. This is the preferred way to interact with git instead of using the raw `bash` or `exec` tools.",
+  usageHint: "ALWAYS prefer this tool over raw shell git commands.\n\nKey fields:\n- `command`: one of the supported subcommands (status, log, diff, commit, etc.)\n- Use `message` only for commit operations.\n- Use `files` array for operations that take paths (status, diff, add, etc.).\n- Non-mutating commands (status, log, diff, branch, fetch) are still permission:confirm for safety.\n- For `commit` in a possibly-shared working tree, pass an explicit `files` list scoped to what YOU changed. A bare commit (no `files`) includes ALL staged changes and may capture another agent's half-done work. Heed the `warning` field on the result.\nNever pass raw git flags through `args` for dangerous operations \u2014 use the structured fields.",
+  permission: "confirm",
+  icon: "git",
+  // Conservative: any of these may mutate. The non-mutating commands
+  // (status/log/diff/branch/fetch) are still gated on `permission: 'confirm'`
+  // and `MUTATING_SUBCOMMANDS` is consulted at runtime for per-call checks.
+  // WS-046: gives permission decisions something to key on.
+  // The git subcommand (status/commit/push) is what a trust rule needs to
+  // distinguish; `git status` and `git push --force` must not share a subject.
+  subjectKey: "command",
+  // `command` is an enum subcommand, so on its own it rendered the subject
+  // `"push"` — and one "always allow" then covered every push, to any branch,
+  // with or without `--force`. These are the fields that change what the call
+  // actually does, so the stored trust rule is as specific as the invocation
+  // the user approved.
+  subjectFields: ["branch", "force", "worktreeAction", "worktreePath", "newBranch"],
+  mutating: true,
+  capabilities: ["fs.write", "shell.restricted"],
+  timeoutMs: TIMEOUT_MS,
+  inputSchema: {
+    type: "object",
+    properties: {
+      command: {
+        type: "string",
+        enum: [
+          "status",
+          "log",
+          "diff",
+          "commit",
+          "branch",
+          "checkout",
+          "stash",
+          "push",
+          "pull",
+          "fetch",
+          "reset",
+          "worktree"
+        ],
+        description: "Git subcommand"
+      },
+      files: {
+        type: "string",
+        description: 'File(s) for status/diff: single path, comma-separated list, or "**/*.ts" glob'
+      },
+      message: { type: "string", description: "Commit message (required for commit)" },
+      branch: { type: "string", description: "Branch name for checkout/branch" },
+      format: {
+        type: "string",
+        enum: ["short", "oneline", "stat", "graph"],
+        description: "Log format (default: short)"
+      },
+      limit: { type: "integer", description: "Limit for log (default: 20)" },
+      dry_run: { type: "boolean", description: "For commit: show what would be committed" },
+      worktreeAction: {
+        type: "string",
+        enum: ["list", "add", "remove", "prune"],
+        description: "Worktree action: list, add, remove, prune"
+      },
+      worktreePath: {
+        type: "string",
+        description: 'Path for worktree add/remove (e.g. "../wt-feature-xyz")'
+      },
+      newBranch: {
+        type: "boolean",
+        description: "Create new branch when adding worktree"
+      },
+      force: {
+        type: "boolean",
+        description: "Force operation (e.g. worktree remove --force)"
+      }
+    },
+    required: ["command"]
+  },
+  async execute(input, ctx, opts) {
+    if (!input?.command) throw new Error("git: command is required");
+    if (input.command === "commit" && !input.message) {
+      return {
+        command: "commit",
+        stdout: "",
+        stderr: "git commit requires a message (-m flag)",
+        exitCode: 1,
+        truncated: false
+      };
+    }
+    const branchGuard = validateBranchInput(input);
+    if (branchGuard) return branchGuard;
+    if (input.command === "worktree") {
+      const guard = validateWorktreeInput(input, ctx.projectRoot);
+      if (guard) return guard;
+    }
+    const gitDir = findGitDir(ctx.cwd, ctx.projectRoot);
+    if (!gitDir) {
+      return {
+        command: input.command,
+        stdout: "",
+        stderr: "Not in a git repository (within project root)",
+        exitCode: 128,
+        truncated: false
+      };
+    }
+    const args = buildArgs(input);
+    let safetyWarning;
+    if (input.command === "commit") {
+      try {
+        const report = await assessCommitSafety({
+          cwd: ctx.cwd,
+          projectRoot: ctx.projectRoot,
+          sessionId: ctx.session?.id,
+          signal: opts.signal
+        });
+        if (report.warning) {
+          const scopeNote = input.files ? "" : "\nNote: this commit has no explicit `files` list, so it will include ALL staged changes. Pass `files` to scope the commit to only what you changed.";
+          safetyWarning = report.warning + scopeNote;
+        }
+      } catch {
+      }
+    }
+    let stagedDiff;
+    if (input.command === "commit" && !input.dry_run) {
+      try {
+        const diffResult = await runGit(["diff", "--cached"], gitDir, opts.signal);
+        if (diffResult.exitCode === 0) {
+          const MAX_DIFF = 2e4;
+          stagedDiff = diffResult.stdout.length > MAX_DIFF ? diffResult.stdout.slice(0, MAX_DIFF) + "\n\n... (diff truncated)" : diffResult.stdout;
+        }
+      } catch {
+      }
+    }
+    const result = await runGit(args, gitDir, opts.signal);
+    if (stagedDiff !== void 0) result.diff = stagedDiff;
+    if (safetyWarning !== void 0) result.warning = safetyWarning;
+    return result;
+  }
+};
+function validateBranchInput(input) {
+  const branch = input.branch;
+  if (branch === void 0) return null;
+  if (!branch.startsWith("-") && !branch.includes(" --")) return null;
+  return {
+    command: input.command,
+    stdout: "",
+    stderr: `unsafe branch name (parsed as a git option): ${branch}`,
+    exitCode: 1,
+    truncated: false
+  };
+}
+function validateWorktreeInput(input, projectRoot) {
+  const reject = (stderr) => ({
+    command: "worktree",
+    stdout: "",
+    stderr,
+    exitCode: 1,
+    truncated: false
+  });
+  if (input.worktreePath?.startsWith("-")) {
+    return reject(`unsafe worktree path: ${input.worktreePath}`);
+  }
+  if ((input.worktreeAction === "add" || input.worktreeAction === "remove") && input.worktreePath) {
+    const root = resolve(projectRoot);
+    const abs = resolve(root, input.worktreePath);
+    if (abs !== root && !abs.startsWith(root + sep)) {
+      return reject(`unsafe worktree path (escapes project root): ${input.worktreePath}`);
+    }
+  }
+  return null;
+}
+function findGitDir(cwd, projectRoot) {
+  const root = projectRoot;
+  let dir = cwd;
+  for (let i = 0; i < 20; i++) {
+    try {
+      const stat = statSync(`${dir}/.git`);
+      if (stat.isDirectory() || stat.isFile()) return dir;
+    } catch {
+    }
+    if (dir === root) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+function buildArgs(input) {
+  const limit = input.limit ?? 20;
+  const files = input.files ? (Array.isArray(input.files) ? input.files : input.files.split(",")).map((s) => s.trim()).filter(Boolean) : [];
+  switch (input.command) {
+    case "status":
+      return ["status", ...files.length ? ["--", ...files] : []];
+    case "log":
+      return [
+        "log",
+        `--max-count=${limit}`,
+        ...input.format === "oneline" ? ["--oneline"] : [],
+        ...input.format === "stat" ? ["--stat"] : [],
+        ...input.format === "graph" ? ["--oneline", "--graph", "--decorate"] : [],
+        ...input.format === "short" || !input.format ? [] : []
+      ];
+    case "diff":
+      return ["diff", "--no-color", ...files.length ? ["--", ...files] : []];
+    case "commit":
+      return [
+        "commit",
+        ...input.dry_run ? ["--dry-run", "--porcelain"] : [],
+        ...input.message ? ["-m", input.message] : [],
+        ...files.length ? ["--", ...files] : []
+      ];
+    case "branch":
+      return input.branch ? [
+        "branch",
+        ...input.branch.startsWith("-") || input.branch.includes(" --") ? [] : [input.branch]
+      ] : ["branch"];
+    case "checkout":
+      if (files.length) return ["checkout", "--", ...files];
+      return input.branch ? ["checkout", input.branch, "--"] : ["checkout"];
+    case "stash":
+      return input.message ? ["stash", "push", "-m", input.message] : ["stash", "push"];
+    case "push":
+      return ["push"];
+    case "pull":
+      return ["pull"];
+    case "fetch":
+      return ["fetch", ...input.branch ? [input.branch] : ["--all"]];
+    case "reset":
+      return ["reset", ...files.length ? ["--", ...files] : []];
+    case "worktree":
+      switch (input.worktreeAction) {
+        case "list":
+          return ["worktree", "list"];
+        case "add": {
+          if (!input.worktreePath) return ["worktree", "list"];
+          const add = ["worktree", "add"];
+          if (input.newBranch && input.branch) add.push("-b", input.branch);
+          add.push(input.worktreePath);
+          if (!input.newBranch && input.branch) add.push(input.branch);
+          return add;
+        }
+        case "remove":
+          return [
+            "worktree",
+            "remove",
+            ...input.force ? ["--force"] : [],
+            input.worktreePath ?? ""
+          ].filter(Boolean);
+        case "prune":
+          return ["worktree", "prune"];
+        default:
+          return ["worktree", "list"];
+      }
+    default:
+      return [input.command];
+  }
+}
+function runGit(args, cwd, signal) {
+  return new Promise((resolve2) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn("git", args, {
+      cwd,
+      signal,
+      env: buildChildEnv(),
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    child.stdout?.on("data", (chunk) => {
+      if (stdout.length < MAX_OUTPUT) {
+        stdout += chunk.toString();
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderr.length < MAX_OUTPUT) {
+        stderr += chunk.toString();
+      }
+    });
+    child.on("error", (err) => {
+      resolve2({
+        command: args[0],
+        stdout: normalizeCommandOutput(stdout),
+        stderr: err.message,
+        exitCode: 1,
+        truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES
+      });
+    });
+    child.on("close", (code) => {
+      resolve2({
+        command: args[0],
+        stdout: normalizeCommandOutput(stdout),
+        stderr: normalizeCommandOutput(stderr),
+        exitCode: code ?? 1,
+        truncated: Buffer.byteLength(stdout, "utf8") > COMMAND_OUTPUT_MAX_BYTES || Buffer.byteLength(stderr, "utf8") > COMMAND_OUTPUT_MAX_BYTES
+      });
+    });
+  });
+}
+
+export {
+  gitTool
+};
+//# sourceMappingURL=chunk-RXISBFR5.js.map

package/dist/chunk-S5CCLZL3.js

@@ -0,0 +1,99 @@
+// src/tool-use.ts
+import {
+  GOVERNED_TOOL_EXECUTOR_META_KEY
+} from "@wrongstack/core/types";
+var toolUseTool = {
+  name: "tool_use",
+  category: "Meta",
+  description: "Directly execute any registered tool by its exact name, bypassing normal discovery. This is a powerful meta-tool intended for cases where the agent has a clear plan and knows precisely which tool to invoke.",
+  usageHint: "ADVANCED META TOOL \u2014 USE WITH CARE:\n\n- Only use when you are certain of the exact tool name and its expected input shape.\n- Prefer using the normal tool calling mechanism when possible.\n- Very useful in batch-tool-use or when orchestrating complex workflows programmatically.\n- The call still goes through full permission checks and capability validation.",
+  permission: "confirm",
+  // WS-046: gives permission decisions something to key on.
+  // The tool being invoked through this indirection — the whole point of a
+  // permission decision here is WHICH tool is being reached.
+  subjectKey: "tool",
+  mutating: true,
+  timeoutMs: 6e4,
+  capabilities: ["tool.mutate.any"],
+  icon: "meta",
+  inputSchema: {
+    type: "object",
+    properties: {
+      tool: {
+        type: "string",
+        description: 'The exact registered name of the tool to invoke (e.g. "bash", "read", "codebase-search").'
+      },
+      input: {
+        type: "object",
+        description: "The input object matching the target tool's inputSchema."
+      }
+    },
+    required: ["tool"]
+  },
+  async execute(input, ctx) {
+    const start = Date.now();
+    if (!input?.tool) {
+      return {
+        tool: "unknown",
+        success: false,
+        error: "tool_use: tool name is required",
+        executionMs: 0
+      };
+    }
+    const tool = (ctx.catalogTools ?? ctx.tools).find((t) => t.name === input.tool);
+    if (!tool) {
+      return {
+        tool: input.tool,
+        success: false,
+        error: `tool_use: tool "${input.tool}" not found`,
+        executionMs: Date.now() - start
+      };
+    }
+    if (tool.name === toolUseTool.name) {
+      return {
+        tool: input.tool,
+        success: false,
+        error: "tool_use: recursive meta-tool execution is not allowed",
+        executionMs: Date.now() - start
+      };
+    }
+    if (tool.permission === "deny") {
+      return {
+        tool: input.tool,
+        success: false,
+        error: `tool_use: tool "${input.tool}" is denied by policy`,
+        executionMs: Date.now() - start
+      };
+    }
+    const governedExecute = ctx.meta[GOVERNED_TOOL_EXECUTOR_META_KEY];
+    if (typeof governedExecute !== "function") {
+      return {
+        tool: input.tool,
+        success: false,
+        error: "tool_use: governed nested execution is unavailable; call the tool directly",
+        executionMs: Date.now() - start
+      };
+    }
+    try {
+      const result = await governedExecute(input.tool, input.input ?? {});
+      return {
+        tool: input.tool,
+        success: result.success,
+        ...result.success ? { result: result.result } : { error: result.error ?? "nested tool failed" },
+        executionMs: Date.now() - start
+      };
+    } catch (e) {
+      return {
+        tool: input.tool,
+        success: false,
+        error: e instanceof Error ? e.message : String(e),
+        executionMs: Date.now() - start
+      };
+    }
+  }
+};
+
+export {
+  toolUseTool
+};
+//# sourceMappingURL=chunk-S5CCLZL3.js.map

package/dist/chunk-SDLVH5RZ.js

@@ -0,0 +1,178 @@
+import {
+  tryLegacyCodeOperation
+} from "./chunk-PQKK5JH7.js";
+import {
+  spawnStream
+} from "./chunk-22B7GE5T.js";
+import {
+  normalizeCommandOutput,
+  safeResolveReal
+} from "./chunk-D33S4RQG.js";
+
+// src/format.ts
+var formatTool = {
+  name: "format",
+  category: "Code Quality",
+  description: "Format source files according to project style (Biome). Can also run in check-only mode.",
+  usageHint: "RUN REGULARLY:\n\n- Use on changed files before committing.\n- `check: true` verifies formatting without making changes (useful in CI-like flows).\nThis project has very consistent formatting expectations. Always ensure your changes are formatted.",
+  permission: "confirm",
+  // WS-046: gives permission decisions something to key on.
+  // The files being rewritten are the subject; the fixer is how, not what.
+  subjectKey: "files",
+  mutating: true,
+  capabilities: ["fs.write", "shell.restricted"],
+  icon: "code",
+  timeoutMs: 6e4,
+  inputSchema: {
+    type: "object",
+    properties: {
+      files: {
+        type: "string",
+        description: "Files/patterns: single path, comma-separated list, or glob"
+      },
+      fixer: {
+        type: "string",
+        enum: ["biome", "prettier", "auto"],
+        description: "Formatter to use (default: auto-detect)"
+      },
+      check: {
+        type: "boolean",
+        description: "Verify only, do not modify files (default: false)"
+      },
+      cwd: { type: "string", description: "Working directory (default: cwd)" }
+    }
+  },
+  async execute(input, ctx, opts) {
+    let final;
+    const executeStream = formatTool.executeStream;
+    if (!executeStream) throw new Error("formatTool: stream execution unavailable");
+    for await (const ev of executeStream(input, ctx, opts)) {
+      if (ev.type === "final") final = ev.output;
+    }
+    if (!final) throw new Error("format: stream ended without final event");
+    return final;
+  },
+  async *executeStream(input, ctx, opts) {
+    const cwd = input.cwd ? await safeResolveReal(input.cwd, ctx) : ctx.cwd;
+    const fixer = input.fixer ?? "auto";
+    if (fixer === "auto" && !input.files) {
+      const op = input.check ? "format-check" : "format-write";
+      const bridge = await tryLegacyCodeOperation(op, {
+        cwd,
+        projectRoot: ctx.projectRoot,
+        signal: opts.signal
+      });
+      if (bridge?.run) {
+        const run = bridge.run;
+        yield {
+          type: "final",
+          output: {
+            fixer: bridge.language,
+            // Language-bridge runs don't report per-file counts.
+            files_checked: void 0,
+            files_changed: void 0,
+            output: normalizeCommandOutput(run.output || run.error || ""),
+            truncated: run.truncated
+          }
+        };
+        return;
+      }
+    }
+    const detected = fixer === "auto" ? await detectFixer(cwd) : fixer;
+    if (!detected) {
+      yield {
+        type: "final",
+        output: {
+          fixer: "none",
+          files_checked: 0,
+          files_changed: 0,
+          output: "No formatter found (biome.json, .prettierrc)",
+          truncated: false
+        }
+      };
+      return;
+    }
+    yield {
+      type: "log",
+      text: `Running ${detected}\u2026`,
+      data: { fixer: detected, check: !!input.check }
+    };
+    const fileList = input.files ? (Array.isArray(input.files) ? input.files : input.files.split(",")).map((f) => f.trim()) : [];
+    let args;
+    if (detected === "prettier") {
+      args = [input.check ? "--check" : "--write"];
+      args.push(...fileList.length > 0 ? fileList : ["."]);
+    } else {
+      args = ["format", input.check ? "--check" : "--write"];
+      if (fileList.length > 0) args.push("--", ...fileList);
+    }
+    const result = yield* spawnStream({
+      cmd: detected,
+      args,
+      cwd,
+      signal: opts.signal,
+      maxBytes: 1e5
+    });
+    const combinedOut = `${result.stdout}
+${result.stderr}`;
+    const counts = parseFormatterCounts(detected, combinedOut);
+    yield {
+      type: "final",
+      output: {
+        fixer: detected,
+        files_checked: counts.checked,
+        files_changed: counts.changed,
+        output: normalizeCommandOutput(result.stdout || result.stderr || result.error || ""),
+        truncated: result.truncated
+      }
+    };
+  }
+};
+function parseFormatterCounts(fixer, output) {
+  if (fixer !== "biome") return { checked: void 0, changed: void 0 };
+  const checkedMatch = /\b(?:Checked|Formatted)\s+(\d+)\s+files?\b/i.exec(output);
+  const changedMatch = /\bFixed\s+(\d+)\s+files?\b/i.exec(output);
+  return {
+    checked: checkedMatch?.[1] !== void 0 ? Number(checkedMatch[1]) : void 0,
+    changed: changedMatch?.[1] !== void 0 ? Number(changedMatch[1]) : void 0
+  };
+}
+async function detectFixer(cwd) {
+  const fs = await import("node:fs/promises");
+  const exists = async (file) => {
+    try {
+      await fs.stat(`${cwd}/${file}`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (await exists("biome.json") || await exists("biome.jsonc")) return "biome";
+  const PRETTIER_CONFIGS = [
+    ".prettierrc",
+    ".prettierrc.json",
+    ".prettierrc.yml",
+    ".prettierrc.yaml",
+    ".prettierrc.js",
+    ".prettierrc.cjs",
+    ".prettierrc.mjs",
+    "prettier.config.js",
+    "prettier.config.cjs",
+    "prettier.config.mjs"
+  ];
+  for (const cfg of PRETTIER_CONFIGS) {
+    if (await exists(cfg)) return "prettier";
+  }
+  try {
+    const raw = await fs.readFile(`${cwd}/package.json`, "utf8");
+    const pkg = JSON.parse(raw);
+    if (pkg["prettier"] !== void 0) return "prettier";
+  } catch {
+  }
+  return "biome";
+}
+
+export {
+  formatTool
+};
+//# sourceMappingURL=chunk-SDLVH5RZ.js.map