@wrongstack/tools 0.310.1 → 0.313.1

package/dist/chunk-PUR6WU2B.js

@@ -0,0 +1,154 @@
+import {
+  checkSyntax
+} from "./chunk-3QMQBO5Z.js";
+import {
+  enqueueReindex
+} from "./chunk-2ME7ZWDD.js";
+import {
+  safeResolveReal,
+  sha256hex,
+  truncateDiffPayload
+} from "./chunk-D33S4RQG.js";
+
+// src/write.ts
+import * as fs from "node:fs/promises";
+import { ToolValidationError } from "@wrongstack/core/types";
+import {
+  atomicWrite,
+  detectNewlineStyle,
+  normalizeToLf,
+  toStyle,
+  unifiedDiff
+} from "@wrongstack/core/utils";
+var MAX_DIFF_BYTES = 262144;
+var writeTool = {
+  name: "write",
+  category: "Filesystem",
+  description: "Write or completely overwrite a file on disk. This is a high-privilege operation. For modifying existing files, you should almost always prefer the `edit` tool instead, because `edit` is safer and works on the last-read version of the file.",
+  usageHint: "RULES FOR CORRECT USAGE:\n- Use `write` primarily for **new files** or when you want to replace the entire content.\n- For any existing file, strongly prefer `edit` (it requires a prior `read` in the same session and is more precise).\n- When overwriting an existing file, the tool reads the current content itself to compute the diff \u2014 but still `read` the file first before large rewrites so you know what you are replacing.\n- When overwriting an existing file, the content is normalized to the dominant line-ending style (CRLF/LF) of the existing file; new files are written verbatim.\n- The path is resolved relative to the project root and protected against escaping the workspace.",
+  selection: {
+    doNotUseWhen: "making a precise change to part of an existing file.",
+    useInstead: ["edit"]
+  },
+  permission: "confirm",
+  // WS-046: gives permission decisions something to key on — the file being
+  // written, so trust rules can scope by path.
+  subjectKey: "path",
+  mutating: true,
+  timeoutMs: 5e3,
+  maxOutputBytes: 262144,
+  capabilities: ["fs.write"],
+  icon: "file",
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Relative path from project root. Must not escape the project."
+      },
+      content: {
+        type: "string",
+        description: "The complete new content of the file."
+      }
+    },
+    required: ["path", "content"]
+  },
+  async execute(input, ctx, opts) {
+    return writeFile(input, ctx, opts?.signal);
+  },
+  async *executeStream(input, ctx, opts) {
+    const prepared = await prepareWrite(input, ctx);
+    if (!prepared.existed) {
+      for (const line of input.content.split("\n")) {
+        yield { type: "partial_output", text: `${line}
+`, data: { livePreview: true } };
+      }
+    }
+    yield { type: "final", output: await finishWrite(input, ctx, prepared, opts?.signal) };
+  }
+};
+async function writeFile(input, ctx, signal) {
+  return finishWrite(input, ctx, await prepareWrite(input, ctx), signal);
+}
+async function prepareWrite(input, ctx) {
+  if (!input?.path) {
+    throw new ToolValidationError({
+      message: "write: path is required",
+      field: "path"
+    });
+  }
+  if (input.content === void 0) {
+    throw new ToolValidationError({
+      message: "write: content is required",
+      field: "content"
+    });
+  }
+  const absPath = await safeResolveReal(input.path, ctx);
+  let existed = false;
+  let prev = "";
+  try {
+    const stat2 = await fs.stat(absPath);
+    existed = stat2.isFile();
+    if (existed) {
+      if (!ctx.hasRead(absPath)) {
+        prev = await fs.readFile(absPath, "utf8");
+        ctx.recordRead(absPath, stat2.mtimeMs, "write", sha256hex(prev));
+      } else {
+        prev = await fs.readFile(absPath, "utf8");
+      }
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+  return { absPath, existed, prev };
+}
+async function finishWrite(input, ctx, prepared, signal) {
+  const content = prepared.existed ? toStyle(normalizeToLf(input.content), detectNewlineStyle(prepared.prev)) : input.content;
+  signal?.throwIfAborted();
+  await atomicWrite(prepared.absPath, content);
+  try {
+    enqueueReindex({ projectRoot: ctx.projectRoot, files: [prepared.absPath] });
+  } catch {
+  }
+  const rawDiff = prepared.existed ? unifiedDiff(prepared.prev, content, { fromFile: input.path, toFile: input.path }) : `+++ ${input.path}
++ (new file, ${content.split("\n").length} lines)`;
+  const { text: diff, truncated: diffTruncated } = truncateDiffPayload(rawDiff, MAX_DIFF_BYTES);
+  const stat2 = await fs.stat(prepared.absPath);
+  ctx.recordRead(prepared.absPath, stat2.mtimeMs, "write", sha256hex(content));
+  ctx.session?.recordFileChange?.({
+    path: prepared.absPath,
+    action: prepared.existed ? "modified" : "created",
+    before: prepared.existed ? prepared.prev : null,
+    after: content
+  });
+  const syntax = await checkSyntax(
+    prepared.absPath,
+    content,
+    prepared.existed ? prepared.prev : void 0
+  ).catch(() => void 0);
+  const hasSyntaxErrors = syntax !== void 0 && syntax.errors.length > 0;
+  const notes = [];
+  if (diffTruncated) {
+    notes.push("Diff truncated to the 256 KiB output budget \u2014 the full write is on disk.");
+  }
+  if (hasSyntaxErrors) {
+    notes.push(
+      syntax.preExisting ? "Syntax check: the file still has parse errors (they pre-date this write) \u2014 see syntax_errors." : `Syntax check: the written content has ${syntax.errors.length} parse error(s) \u2014 fix them now, see syntax_errors.`
+    );
+  }
+  return {
+    path: prepared.absPath,
+    bytes_written: Buffer.byteLength(content, "utf8"),
+    created: !prepared.existed,
+    diff,
+    syntax_errors: hasSyntaxErrors ? syntax.errors : void 0,
+    note: notes.length > 0 ? notes.join("\n") : void 0
+  };
+}
+
+export {
+  writeTool
+};
+//# sourceMappingURL=chunk-PUR6WU2B.js.map

package/dist/chunk-Q5JPPCZC.js

@@ -0,0 +1,12 @@
+// src/_regex.ts
+import {
+  capSubject,
+  compileUserRegex,
+  MAX_SUBJECT_LEN
+} from "@wrongstack/primitives";
+
+export {
+  capSubject,
+  compileUserRegex
+};
+//# sourceMappingURL=chunk-Q5JPPCZC.js.map

package/dist/chunk-QBV725YG.js

@@ -0,0 +1,128 @@
+// src/tool-help.ts
+var toolHelpTool = {
+  name: "tool_help",
+  category: "Meta",
+  description: "Get detailed help for a specific tool, including its full input schema and usage guidance. If you do not know which tool to use, search with `tool_search` first, then call this with the tool name.",
+  usageHint: "USE WHEN YOU NEED PRECISE TOOL INFORMATION:\n\n- Call with a specific `tool` name when you want the full schema and current usageHint.\n- Omit `tool` to get an overview of all available tools.\n- Different `format` options give you different levels of detail.\n- Tip: use `tool_search` to find the right tool name, then `tool_help` for the full schema.\nThis tool is extremely valuable for self-correction when you are unsure about a tool's interface.",
+  permission: "auto",
+  mutating: false,
+  timeoutMs: 5e3,
+  capabilities: ["tool.meta"],
+  icon: "meta",
+  inputSchema: {
+    type: "object",
+    properties: {
+      tool: {
+        type: "string",
+        description: "Specific tool name to get detailed help for. Omit to get a list of all tools."
+      },
+      format: {
+        type: "string",
+        enum: ["short", "full", "markdown"],
+        description: 'Level of detail: "short" (summary), "full" (with full schema), "markdown" (human readable).'
+      },
+      include_examples: {
+        type: "boolean",
+        description: "Whether to include example usage in the response."
+      }
+    }
+  },
+  async execute(input, ctx) {
+    const format = input.format ?? "short";
+    const includeExamples = input.include_examples ?? false;
+    if (input.tool) {
+      const tool = (ctx.catalogTools ?? ctx.tools).find((t) => t.name === input.tool);
+      if (!tool) {
+        return {
+          tool: input.tool,
+          help: `No tool found with name "${input.tool}"`,
+          tools: [],
+          total: 0
+        };
+      }
+      return {
+        tool: tool.name,
+        help: formatToolHelp(tool, format, includeExamples),
+        tools: [
+          {
+            name: tool.name,
+            description: tool.description,
+            usageHint: tool.usageHint ?? "",
+            inputSchema: tool.inputSchema,
+            permission: tool.permission,
+            mutating: tool.mutating
+          }
+        ],
+        total: 1
+      };
+    }
+    const allTools = (ctx.catalogTools ?? ctx.tools).map((t) => ({
+      name: t.name,
+      description: t.description,
+      usageHint: t.usageHint ?? "",
+      inputSchema: format === "full" ? t.inputSchema : void 0,
+      permission: t.permission,
+      mutating: t.mutating
+    }));
+    return {
+      help: format === "markdown" ? formatAllToolsMarkdown(allTools) : formatAllToolsShort(allTools),
+      tools: allTools,
+      total: allTools.length
+    };
+  }
+};
+function formatToolHelp(tool, format, includeExamples) {
+  const lines = [];
+  if (format === "short") {
+    lines.push(`${tool.name}: ${tool.description}`);
+    if (tool.usageHint) lines.push(`Hint: ${tool.usageHint}`);
+    return lines.join("\n");
+  }
+  if (format === "markdown") {
+    lines.push(`## ${tool.name}`);
+    lines.push("");
+    lines.push(tool.description);
+    lines.push("");
+    lines.push("**Permission:** " + tool.permission);
+    lines.push("**Mutating:** " + (tool.mutating ? "yes" : "no"));
+    if (tool.usageHint) {
+      lines.push("");
+      lines.push("### Usage Hint");
+      lines.push(tool.usageHint);
+    }
+    if (includeExamples && tool.inputSchema) {
+      lines.push("");
+      lines.push("### Input Schema");
+      lines.push("```json");
+      lines.push(JSON.stringify(tool.inputSchema, null, 2));
+      lines.push("```");
+    }
+    return lines.join("\n");
+  }
+  lines.push(`Tool: ${tool.name}`);
+  lines.push(`Description: ${tool.description}`);
+  lines.push(`Permission: ${tool.permission}`);
+  lines.push(`Mutating: ${tool.mutating}`);
+  if (tool.usageHint) lines.push(`Usage: ${tool.usageHint}`);
+  if (format === "full" && tool.inputSchema) {
+    lines.push("Schema: " + JSON.stringify(tool.inputSchema, null, 2));
+  }
+  return lines.join("\n");
+}
+function formatAllToolsShort(tools) {
+  return tools.map((t) => `  ${t.name.padEnd(16)} ${t.description}`).join("\n");
+}
+function formatAllToolsMarkdown(tools) {
+  const lines = ["## Available Tools", ""];
+  lines.push("| Tool | Description |");
+  lines.push("|------|-------------|");
+  for (const t of tools) {
+    lines.push(`| \`${t.name}\` | ${t.description} |`);
+  }
+  return lines.join("\n");
+}
+
+export {
+  toolHelpTool
+};
+//# sourceMappingURL=chunk-QBV725YG.js.map