@chantier/tools 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes are documented in the root
+[CHANGELOG.md](../../CHANGELOG.md).
+
+## 0.3.0 — 2026-09-16
+
+- grep: output modes and pagination, plus guidance in the no-match case.
+- read: continuation notices when output is truncated.
+- bash: output spills to a file past the size cap; working-directory control.
+- edit: CRLF handling and a diff channel for reviewing changes.
+
+See the root changelog for the full list.

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      4. (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 DASHLEA × MLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,12 @@
+# @chantier/tools
+
+The seven built-in tools of the [chantier](https://github.com/mlcassociation/chantier)
+coding agent: bash, edit, glob, grep, read, webfetch, and write. Each returns
+model-facing prose (not stack traces) and never executes a mutation without an
+allow decision from the permission engine.
+
+```ts
+import { buildTools } from "@chantier/tools";
+```
+
+License: Apache-2.0.

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+import { ToolDefinition } from "@chantier/core";
+//#region src/bash.d.ts
+export declare const bashTool: ToolDefinition;
+//#endregion
+//#region src/edit.d.ts
+export declare const editTool: ToolDefinition;
+//#endregion
+//#region src/glob.d.ts
+export declare const globTool: ToolDefinition;
+//#endregion
+//#region src/grep.d.ts
+export declare const grepTool: ToolDefinition;
+//#endregion
+//#region src/read.d.ts
+export declare const readTool: ToolDefinition;
+//#endregion
+//#region src/webfetch.d.ts
+export declare const webfetchTool: ToolDefinition;
+/** Naive HTML → text: drop script/style blocks, strip tags, decode common entities. */
+export declare function htmlToText(html: string): string;
+//#endregion
+//#region src/write.d.ts
+export declare const writeTool: ToolDefinition;
+//#endregion
+//#region src/common.d.ts
+/** Model-facing tool output is capped at this many chars, with a visible note. */
+export declare const MAX_TOOL_OUTPUT_CHARS = 40000;
+export declare function truncateOutput(text: string, maxChars?: number): string;
+/**
+ * Deny-first read protection, enforced inside the file tools (defense in depth,
+ * independent of permission rules): .env, .env.*, *.pem, id_rsa*, ~/.ssh/**.
+ */
+export declare function isDenyReadPath(resolvedPath: string): boolean;
+export declare function denyReadMessage(resolvedPath: string): string;
+/**
+ * Resolves a tool input path against the project cwd. Absolute paths are allowed
+ * as-is (user-specified); relative paths resolve inside cwd.
+ */
+export declare function resolveInCwd(cwd: string, inputPath: string): string;
+/** Formats file text with 1-indexed line numbers, optionally windowed. */
+export declare function formatNumbered(text: string, offset?: number, limit?: number): string;
+/** Parses a tool input field as a string, with a model-facing prose error. */
+export declare function requireString(input: Record<string, unknown>, field: string): string | undefined;
+//#endregion
+//#region src/index.d.ts
+/** The seven v0.1 built-in tools. */
+export declare function buildTools(): ToolDefinition[];
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,708 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { homedir } from "node:os";
+import { createTwoFilesPatch } from "diff";
+import { glob } from "tinyglobby";
+//#region src/common.ts
+/** Model-facing tool output is capped at this many chars, with a visible note. */
+const MAX_TOOL_OUTPUT_CHARS = 4e4;
+function truncateOutput(text, maxChars = MAX_TOOL_OUTPUT_CHARS) {
+	if (text.length <= maxChars) return text;
+	return `${text.slice(0, maxChars)}\n[truncated: showing first ${maxChars} of ${text.length} chars]`;
+}
+/**
+* Deny-first read protection, enforced inside the file tools (defense in depth,
+* independent of permission rules): .env, .env.*, *.pem, id_rsa*, ~/.ssh/**.
+*/
+function isDenyReadPath(resolvedPath) {
+	const base = path.basename(resolvedPath);
+	if (base === ".env" || base.startsWith(".env.")) return true;
+	if (base.endsWith(".pem")) return true;
+	if (base.startsWith("id_rsa")) return true;
+	const home = homedir();
+	if ((resolvedPath.startsWith("~") ? path.join(home, resolvedPath.slice(1)) : resolvedPath).split(path.sep).includes(".ssh")) return true;
+	return false;
+}
+function denyReadMessage(resolvedPath) {
+	return `Error: ${resolvedPath} is protected (deny-read list: .env, .env.*, *.pem, id_rsa*, ~/.ssh/**). This path cannot be read, listed, or searched.`;
+}
+/**
+* Resolves a tool input path against the project cwd. Absolute paths are allowed
+* as-is (user-specified); relative paths resolve inside cwd.
+*/
+function resolveInCwd(cwd, inputPath) {
+	return path.isAbsolute(inputPath) ? path.normalize(inputPath) : path.normalize(path.join(cwd, inputPath));
+}
+/** Formats file text with 1-indexed line numbers, optionally windowed. */
+function formatNumbered(text, offset = 1, limit) {
+	const lines = text.split("\n");
+	const start = Math.max(1, offset);
+	const end = limit === void 0 ? lines.length : Math.min(lines.length, start - 1 + limit);
+	const window = lines.slice(start - 1, end);
+	const width = String(end).length;
+	return window.map((line, i) => `${String(start + i).padStart(width)}: ${line}`).join("\n");
+}
+/** Parses a tool input field as a string, with a model-facing prose error. */
+function requireString(input, field) {
+	const value = input[field];
+	if (typeof value === "string") return value;
+}
+//#endregion
+//#region src/bash.ts
+const DEFAULT_TIMEOUT_MS = 12e4;
+/** Captured output beyond which the full buffer is spilled to a file instead of being truncated away. */
+const SPILL_THRESHOLD = 14e4;
+/** Tail length kept in the tool result when a spill happens. */
+const SPILL_TAIL_CHARS = 1e4;
+/**
+* Absolute last resort: the command is killed once in-memory accumulation passes
+* this (a runaway producer that even a spill file cannot serve within reason).
+*/
+const HARD_CAP_CHARS = 10485760;
+const bashTool = {
+	name: "bash",
+	description: "Run a shell command under /bin/sh. stdout and stderr are captured and the exit code is reported. Pass `workdir` to run the command in another directory (resolved relative to the project cwd; it must already exist). Commands are killed after the timeout (default 120 s). When output exceeds the tool cap, the full output is saved to a file under <cwd>/.chantier/spill/ and only the last ~10k characters are returned with a header naming the spill file.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			command: {
+				type: "string",
+				description: "Shell command to run"
+			},
+			workdir: {
+				type: "string",
+				description: "Directory to run the command in, relative to the project cwd (must exist; default: project cwd)"
+			},
+			timeoutMs: {
+				type: "number",
+				description: "Kill the command after this many milliseconds (default 120000)"
+			}
+		},
+		required: ["command"]
+	},
+	readOnly: false,
+	specifier: (input) => typeof input.command === "string" ? input.command : void 0,
+	handler: async (input, ctx) => {
+		const command = typeof input.command === "string" ? input.command : void 0;
+		if (command === void 0 || command.length === 0) return "Error: the `command` argument is required and must be a non-empty string.";
+		let runCwd = ctx.cwd;
+		const workdirInput = typeof input.workdir === "string" ? input.workdir : void 0;
+		if (workdirInput !== void 0) {
+			const resolvedWorkdir = resolveInCwd(ctx.cwd, workdirInput);
+			const info = await stat(resolvedWorkdir).catch(() => null);
+			if (info === null) return `Error: workdir ${resolvedWorkdir} does not exist. Create it first (e.g. bash: mkdir -p ${workdirInput}) or pass a directory that exists under ${ctx.cwd}.`;
+			if (!info.isDirectory()) return `Error: workdir ${resolvedWorkdir} is not a directory. Pass a directory path.`;
+			runCwd = resolvedWorkdir;
+		}
+		const timeoutMs = typeof input.timeoutMs === "number" && input.timeoutMs > 0 ? Math.floor(input.timeoutMs) : DEFAULT_TIMEOUT_MS;
+		return truncateOutput(await runShell(command, runCwd, timeoutMs, ctx.signal));
+	}
+};
+function runShell(command, cwd, timeoutMs, signal) {
+	const { promise, resolve } = Promise.withResolvers();
+	const child = spawn("/bin/sh", ["-c", command], {
+		cwd,
+		signal,
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		detached: true
+	});
+	let stdout = "";
+	let stderr = "";
+	let hardCapped = false;
+	child.stdout.setEncoding("utf8");
+	child.stderr.setEncoding("utf8");
+	child.stdout.on("data", (chunk) => {
+		stdout += chunk;
+	});
+	child.stderr.on("data", (chunk) => {
+		stderr += chunk;
+	});
+	const killTree = () => {
+		try {
+			if (child.pid !== void 0) process.kill(-child.pid, "SIGKILL");
+			else child.kill("SIGKILL");
+		} catch {
+			child.kill("SIGKILL");
+		}
+	};
+	const hardCapTimer = setInterval(() => {
+		if (stdout.length + stderr.length > HARD_CAP_CHARS) {
+			hardCapped = true;
+			killTree();
+		}
+	}, 250);
+	const timer = setTimeout(killTree, timeoutMs);
+	const finish = (result) => {
+		clearTimeout(timer);
+		clearInterval(hardCapTimer);
+		resolve(result);
+	};
+	child.on("error", (error) => {
+		finish(`\nError: failed to spawn shell: ${error.message}`);
+	});
+	child.on("close", (code, signalKilled) => {
+		finalize(code, signalKilled);
+	});
+	const finalize = async (code, signalKilled) => {
+		const combined = `${stdout}${stderr.length > 0 ? (stdout.length > 0 ? "\n--- stderr ---\n" : "") + stderr : ""}`;
+		let body = combined;
+		if (combined.length > SPILL_THRESHOLD) body = await spilledBody(combined, cwd, command, hardCapped);
+		finish(`${body}${exitTail(code, signalKilled, timeoutMs)}`);
+	};
+	return promise;
+}
+/** Header + tail for an over-cap run; undefined spillPath falls back to a truncated body. */
+async function spilledBody(combined, cwd, command, hardCapped) {
+	const spillPath = await writeSpillFile(combined, cwd, command);
+	if (spillPath === void 0) return `[output exceeded cap (${combined.length} chars) and the spill file could not be written]\n${combined.slice(0, MAX_TOOL_OUTPUT_CHARS)}`;
+	const tail = combined.slice(Math.max(0, combined.length - SPILL_TAIL_CHARS));
+	return `${hardCapped ? `[command killed: accumulated output passed the 10 MB in-memory cap]\n` : ""}[output exceeded cap \u2014 full output (${combined.length} chars) saved to ${spillPath}]\n${tail}`;
+}
+/** Writes the full captured output to <cwd>/.chantier/spill/<iso>-<sha8(command)>.txt. */
+async function writeSpillFile(combined, cwd, command) {
+	try {
+		const spillDir = path.join(cwd, ".chantier", "spill");
+		await mkdir(spillDir, { recursive: true });
+		const stamp = (/* @__PURE__ */ new Date()).toISOString();
+		const hash = createHash("sha256").update(command).digest("hex").slice(0, 8);
+		const spillPath = path.join(spillDir, `${stamp}-${hash}.txt`);
+		await writeFile(spillPath, combined, "utf8");
+		return spillPath;
+	} catch {
+		return;
+	}
+}
+function exitTail(code, signalKilled, timeoutMs) {
+	if (signalKilled !== null && (signalKilled === "SIGKILL" || signalKilled === "SIGTERM")) return `\nCommand killed (signal ${signalKilled}) after ${timeoutMs} ms.`;
+	return `\nExit code: ${code === null ? `signal ${String(signalKilled)}` : `${code}${code === 1 ? ` (exit 1 \u2014 commonly means "no results" for grep/rg/diff/test; not necessarily an error)` : ""}`}`;
+}
+//#endregion
+//#region src/edit.ts
+function countOccurrences(haystack, needle) {
+	if (needle.length === 0) return 0;
+	let count = 0;
+	let index = haystack.indexOf(needle);
+	while (index !== -1) {
+		count += 1;
+		index = haystack.indexOf(needle, index + 1);
+	}
+	return count;
+}
+/** Dominant line ending of a file; ties and pure-LF files are treated as LF. */
+function dominantEol(text) {
+	const crlf = countOccurrences(text, "\r\n");
+	return crlf > countOccurrences(text, "\n") - crlf ? "\r\n" : "\n";
+}
+/**
+* Applies oldString → newString on `original`. When the file is CRLF-dominant and
+* the exact match misses, oldString's `\n` are retried as `\r\n` (models write LF);
+* the replacement text is normalized to the file's dominant ending either way.
+*/
+function planEdit(original, oldString, newString, replaceAll) {
+	const crlfFile = dominantEol(original) === "\r\n";
+	let target = oldString;
+	let crlfRetry = false;
+	let matches = countOccurrences(original, oldString);
+	if (matches === 0 && crlfFile && oldString.includes("\n")) {
+		const crlfOld = oldString.replace(/\r?\n/g, "\r\n");
+		const crlfMatches = countOccurrences(original, crlfOld);
+		if (crlfMatches > 0) {
+			target = crlfOld;
+			crlfRetry = true;
+			matches = crlfMatches;
+		}
+	}
+	if (matches === 0) {
+		const snippet = oldString.length > 200 ? `${oldString.slice(0, 200)}\u2026` : oldString;
+		return {
+			ok: false,
+			kind: "not-found",
+			error: `The match is exact (whitespace and indentation included). Read the file around your target and copy the text verbatim. You sent:\n${JSON.stringify(snippet)}`
+		};
+	}
+	if (matches > 1 && !replaceAll) return {
+		ok: false,
+		kind: "ambiguous",
+		count: matches,
+		error: "Include more surrounding context to make it unique, or pass `replaceAll: true` if every occurrence should change."
+	};
+	const normalizedNew = crlfFile ? newString.replace(/\r?\n/g, "\r\n") : newString.replace(/\r\n/g, "\n");
+	return {
+		ok: true,
+		updated: replaceAll === true ? original.split(target).join(normalizedNew) : original.replace(target, normalizedNew),
+		matchCount: matches,
+		crlfFile,
+		crlfRetry
+	};
+}
+/** Unified diff (a/<rel> → b/<rel>) of the planned edit, for the approval card. */
+async function editAskDetail(input, ctx) {
+	const raw = requireString(input, "path");
+	const oldString = requireString(input, "oldString");
+	const newString = requireString(input, "newString");
+	if (raw === void 0 || oldString === void 0 || oldString.length === 0 || newString === void 0) return void 0;
+	const resolved = resolveInCwd(ctx.cwd, raw);
+	const original = await readFile(resolved, "utf8").catch(() => void 0);
+	if (original === void 0) return void 0;
+	const plan = planEdit(original, oldString, newString, input.replaceAll === true);
+	if (!plan.ok) return void 0;
+	const rel = path.relative(ctx.cwd, resolved);
+	return { diff: createTwoFilesPatch(`a/${rel}`, `b/${rel}`, original, plan.updated, void 0, void 0, { context: 3 }) };
+}
+const editTool = {
+	name: "edit",
+	description: "Replace an exact unique string in a file with new text. The oldString must match exactly once; if it is ambiguous, include more surrounding context or pass replaceAll: true. Read the file first. CRLF files keep their line endings: if your oldString uses \\n and misses, the tool retries it as \\r\\n.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			path: {
+				type: "string",
+				description: "File path, relative to the project cwd"
+			},
+			oldString: {
+				type: "string",
+				description: "Exact text to replace (must be unique unless replaceAll)"
+			},
+			newString: {
+				type: "string",
+				description: "Replacement text"
+			},
+			replaceAll: {
+				type: "boolean",
+				description: "Replace every occurrence instead of requiring uniqueness"
+			}
+		},
+		required: [
+			"path",
+			"oldString",
+			"newString"
+		]
+	},
+	readOnly: false,
+	specifier: (input) => requireString(input, "path"),
+	askDetail: editAskDetail,
+	handler: async (input, ctx) => {
+		const raw = requireString(input, "path");
+		const oldString = requireString(input, "oldString");
+		const newString = requireString(input, "newString");
+		if (raw === void 0) return "Error: the `path` argument is required and must be a string.";
+		if (oldString === void 0 || oldString.length === 0) return "Error: the `oldString` argument is required, must be a string, and must not be empty.";
+		if (newString === void 0) return "Error: the `newString` argument is required and must be a string.";
+		const resolved = resolveInCwd(ctx.cwd, raw);
+		const existing = await stat(resolved).catch(() => null);
+		if (existing === null || !existing.isFile()) return `Error: no file at ${resolved}. Use the read tool first to confirm the exact path.`;
+		const plan = planEdit(await readFile(resolved, "utf8"), oldString, newString, input.replaceAll === true);
+		if (!plan.ok) return plan.kind === "not-found" ? `Error: oldString not found in ${resolved}. ${plan.error}` : `Error: oldString appears ${plan.count} times in ${resolved}. ${plan.error}`;
+		await writeFile(resolved, plan.updated, "utf8");
+		const changed = input.replaceAll === true ? `${plan.matchCount} occurrence(s)` : "1 occurrence";
+		const eolNote = plan.crlfFile ? plan.crlfRetry ? " (CRLF line endings preserved; oldString matched after an LF→CRLF retry)" : " (CRLF line endings preserved)" : "";
+		return truncateOutput(`Edited ${resolved}: replaced ${changed} (${oldString.length} → ${newString.length} chars)${eolNote}.`);
+	}
+};
+//#endregion
+//#region src/glob.ts
+const globTool = {
+	name: "glob",
+	description: "Find files matching a glob pattern (e.g. `src/**/*.ts`). Results are sorted lexicographically.",
+	inputSchema: {
+		type: "object",
+		properties: { pattern: {
+			type: "string",
+			description: "Glob pattern, relative to the project cwd"
+		} },
+		required: ["pattern"]
+	},
+	readOnly: true,
+	specifier: (input) => typeof input.pattern === "string" ? input.pattern : void 0,
+	handler: async (input, ctx) => {
+		const pattern = typeof input.pattern === "string" ? input.pattern : void 0;
+		if (pattern === void 0 || pattern.length === 0) return "Error: the `pattern` argument is required and must be a non-empty glob string.";
+		const rgResult = await tryRgFiles(pattern, ctx.cwd);
+		if (rgResult !== null) {
+			if (rgResult === "") return "No files match this pattern.";
+			return truncateOutput(rgResult.split("\n").sort((a, b) => a.localeCompare(b)).join("\n"));
+		}
+		const files = await glob({
+			patterns: [pattern],
+			cwd: ctx.cwd,
+			dot: true
+		});
+		if (files.length === 0) return "No files match this pattern.";
+		return truncateOutput(files.sort((a, b) => a.localeCompare(b)).join("\n"));
+	}
+};
+/** `rg --files -g` when ripgrep is installed; null = unavailable (fallback needed). */
+async function tryRgFiles(pattern, cwd) {
+	const { promise, resolve } = Promise.withResolvers();
+	const child = spawn("rg", [
+		"--files",
+		"--hidden",
+		"--no-messages",
+		"-g",
+		pattern
+	], { cwd });
+	let stdout = "";
+	child.stdout.setEncoding("utf8");
+	child.stdout.on("data", (chunk) => {
+		stdout += chunk;
+	});
+	child.on("error", () => resolve(null));
+	child.on("close", (code) => {
+		if (code === null || code !== 0 && code !== 1) resolve(null);
+		else resolve(stdout.trimEnd());
+	});
+	return promise;
+}
+//#endregion
+//#region src/grep.ts
+const MAX_LINES = 100;
+const MAX_MATCHES_PER_FILE = 50;
+const grepTool = {
+	name: "grep",
+	description: "Search file contents with a regular expression (case-sensitive, matches anywhere in a line). Mode `content` (default) returns `file:line:text` lines; mode `files_with_matches` returns only matching file paths. Results are capped at 100 entries unless `head_limit` is given (max per file: 50). Use `offset` + `head_limit` to page through large result sets. Pass `path` to search a subtree and `glob` to filter files (e.g. `*.ts`). Protected paths are skipped. When nothing matches, the tool suggests how to widen the search.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			pattern: {
+				type: "string",
+				description: "Regular expression to search for"
+			},
+			path: {
+				type: "string",
+				description: "Directory or file to search (default: project cwd)"
+			},
+			glob: {
+				type: "string",
+				description: "File glob filter, e.g. `*.ts`"
+			},
+			mode: {
+				type: "string",
+				enum: ["content", "files_with_matches"],
+				description: "content: file:line:text lines (default). files_with_matches: matching file paths only"
+			},
+			head_limit: {
+				type: "number",
+				description: "Maximum number of entries (lines or files) to return (default 100)"
+			},
+			offset: {
+				type: "number",
+				description: "Skip the first N entries before applying head_limit"
+			}
+		},
+		required: ["pattern"]
+	},
+	readOnly: true,
+	specifier: (input) => typeof input.pattern === "string" ? input.pattern : void 0,
+	handler: async (input, ctx) => {
+		const pattern = typeof input.pattern === "string" ? input.pattern : void 0;
+		if (pattern === void 0 || pattern.length === 0) return "Error: the `pattern` argument is required and must be a non-empty regular expression.";
+		let regex;
+		try {
+			regex = new RegExp(pattern);
+		} catch (error) {
+			return `Error: invalid regular expression: ${error.message}`;
+		}
+		const modeInput = typeof input.mode === "string" ? input.mode : void 0;
+		if (modeInput !== void 0 && modeInput !== "content" && modeInput !== "files_with_matches") return "Error: mode must be \"content\" or \"files_with_matches\".";
+		const mode = modeInput === "files_with_matches" ? "files_with_matches" : "content";
+		const headLimit = typeof input.head_limit === "number" ? Math.floor(input.head_limit) : MAX_LINES;
+		if (headLimit <= 0) return "Error: head_limit must be a positive integer.";
+		const offset = typeof input.offset === "number" ? Math.floor(input.offset) : 0;
+		if (offset < 0) return "Error: offset must be a non-negative integer.";
+		const searchPath = typeof input.path === "string" ? input.path : ".";
+		const globFilter = typeof input.glob === "string" ? input.glob : void 0;
+		const entries = await tryRg(pattern, ctx.cwd, searchPath, globFilter, mode) ?? await jsFallback(regex, ctx.cwd, searchPath, globFilter, mode);
+		if (entries.length === 0) return noMatchesMessage(pattern);
+		return pageResults(entries, offset, headLimit);
+	}
+};
+/** Corrective prose for an empty result set; shared by the rg fast path and the JS fallback. */
+function noMatchesMessage(pattern) {
+	return `No matches for ${JSON.stringify(pattern)}. The regex is case-sensitive and matches anywhere in a line. Try a simpler pattern, check spelling and escaping (regex metacharacters like \`.\` and \`(\` need backslashes), broaden the \`glob\` filter or drop it, or widen \`path\` to the whole project.`;
+}
+/**
+* Applies offset/head_limit pagination to an ordered result list and renders the page.
+* Appends a continuation notice when entries remain beyond the window.
+*/
+function pageResults(entries, offset, headLimit) {
+	if (offset >= entries.length) {
+		const plural = entries.length === 1 ? "entry" : "entries";
+		return `Error: offset ${offset} is past the end (${entries.length} ${plural} total). Re-run with a smaller offset.`;
+	}
+	const page = entries.slice(offset, offset + headLimit);
+	const end = offset + page.length;
+	const body = page.join("\n");
+	if (end < entries.length) return truncateOutput(`${body}\n[${entries.length} entries total; showing ${offset + 1}\u2013${end}; re-run with offset=${end} for the next page]`);
+	return truncateOutput(body);
+}
+/**
+* Ripgrep fast path. Returns the raw entry lines (content mode: `file:line:text`,
+* files mode: file paths), or null when rg is unavailable or errored (caller
+* falls back to the JS walker). No-match (exit 1) is an empty list, not null.
+*/
+async function tryRg(pattern, cwd, searchPath, globFilter, mode) {
+	const { promise, resolve } = Promise.withResolvers();
+	const globArgs = globFilter === void 0 ? [] : ["--glob", globFilter];
+	const args = [
+		...mode === "content" ? [
+			"-n",
+			"--max-count",
+			String(MAX_MATCHES_PER_FILE)
+		] : ["-l"],
+		"--hidden",
+		"--no-messages",
+		...globArgs,
+		pattern,
+		searchPath
+	];
+	const child = spawn("rg", args, { cwd });
+	let stdout = "";
+	child.stdout.setEncoding("utf8");
+	child.stdout.on("data", (chunk) => {
+		stdout += chunk;
+	});
+	child.on("error", () => resolve(null));
+	child.on("close", (code) => {
+		if (code === null || code !== 0 && code !== 1) {
+			resolve(null);
+			return;
+		}
+		const kept = stdout.split("\n").filter((line) => line.length > 0).filter((line) => {
+			const file = mode === "content" ? line.split(":")[0] ?? "" : line;
+			return file.length === 0 || !isDenyReadPath(path.resolve(cwd, file));
+		});
+		resolve(kept);
+	});
+	return promise;
+}
+/** Line-walk fallback when rg is unavailable; protected paths are skipped. */
+async function jsFallback(regex, cwd, searchPath, globFilter, mode) {
+	const base = path.resolve(cwd, searchPath);
+	const patterns = globFilter === void 0 ? ["**/*"] : [`**/${globFilter}`, globFilter];
+	const files = await glob({
+		patterns,
+		cwd: base,
+		dot: true,
+		deep: 10
+	});
+	const entries = [];
+	for (const file of files.slice().sort((a, b) => a.localeCompare(b))) {
+		const absolute = path.join(base, file);
+		if (isDenyReadPath(absolute)) continue;
+		const content = await readFile(absolute, "utf8").catch(() => null);
+		if (content === null) continue;
+		const display = searchPath === "." ? file : path.join(searchPath, file);
+		const fileLines = content.split("\n");
+		if (mode === "files_with_matches") {
+			if (fileLines.some((line) => regex.test(line))) entries.push(display);
+			continue;
+		}
+		let shown = 0;
+		for (let i = 0; i < fileLines.length && shown < MAX_MATCHES_PER_FILE; i++) if (regex.test(fileLines[i] ?? "")) {
+			entries.push(`${display}:${i + 1}:${fileLines[i]}`);
+			shown += 1;
+		}
+	}
+	return entries;
+}
+//#endregion
+//#region src/read.ts
+const DEFAULT_LINE_LIMIT = 2e3;
+const readTool = {
+	name: "read",
+	description: "Read a file as numbered text (1-indexed). With offset/limit you can window large files; when output is cut short the result ends with a continuation notice naming the offset to resume from. Passing a directory path lists its entries (depth 1). Protected paths (.env*, *.pem, id_rsa*, ~/.ssh) are refused.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			path: {
+				type: "string",
+				description: "File or directory path, relative to the project cwd"
+			},
+			offset: {
+				type: "number",
+				description: "1-indexed first line to show"
+			},
+			limit: {
+				type: "number",
+				description: "Maximum number of lines to show"
+			}
+		},
+		required: ["path"]
+	},
+	readOnly: true,
+	specifier: (input) => requireString(input, "path"),
+	handler: async (input, ctx) => {
+		const raw = requireString(input, "path");
+		if (raw === void 0) return "Error: the `path` argument is required and must be a string.";
+		const resolved = resolveInCwd(ctx.cwd, raw);
+		if (isDenyReadPath(resolved)) return denyReadMessage(resolved);
+		const info = await stat(resolved).catch((error) => error);
+		if (info instanceof Error) {
+			if (info.code !== "ENOENT") return `Error: could not access ${resolved}: ${String(info.message)}`;
+			return missingFileMessage(resolved);
+		}
+		if (info.isDirectory()) return truncateOutput((await readdir(resolved, { withFileTypes: true })).map((entry) => entry.isDirectory() ? `${entry.name}/` : entry.name).sort((a, b) => a.localeCompare(b)).map((name) => name).join("\n"));
+		const offset = typeof input.offset === "number" ? Math.floor(input.offset) : 1;
+		const limit = typeof input.limit === "number" && input.limit > 0 ? Math.floor(input.limit) : DEFAULT_LINE_LIMIT;
+		return readFileWindow(await readFile(resolved, "utf8"), offset, limit);
+	}
+};
+/**
+* Windows `text` into numbered lines and appends the continuation notice when the
+* window (line limit or the char cap) cuts the file before its end.
+*/
+function readFileWindow(text, offset, limit) {
+	const total = text.split("\n").length;
+	const start = Math.max(1, offset);
+	if (start > total) return `Error: offset ${offset} is past the end of the file (${total} lines). Re-read with a smaller offset.`;
+	const end = Math.min(total, start - 1 + limit);
+	let numbered = formatNumbered(text, offset, limit);
+	let shownEnd = end;
+	if (numbered.length > 4e4) {
+		const cut = numbered.slice(0, MAX_TOOL_OUTPUT_CHARS);
+		const lastNewline = cut.lastIndexOf("\n");
+		numbered = lastNewline === -1 ? cut : cut.slice(0, lastNewline);
+		shownEnd = start - 1 + numbered.split("\n").length;
+	}
+	if (shownEnd < total) numbered += `\n[truncated \u2014 showing lines ${start}\u2013${shownEnd} of ${total}; re-read with offset=${shownEnd + 1} for the continuation]`;
+	return numbered;
+}
+/**
+* Corrective prose for a missing path: list nearby files so the model can recover.
+* Only ENOENT reaches this helper; other stat errors are reported inline.
+*/
+async function missingFileMessage(resolved) {
+	const dir = path.dirname(resolved);
+	let nearby = [];
+	try {
+		nearby = await glob({
+			patterns: ["*"],
+			cwd: dir,
+			dot: true,
+			deep: 1
+		});
+	} catch {
+		nearby = [];
+	}
+	const listing = nearby.slice(0, 20).sort((a, b) => a.localeCompare(b));
+	return `Error: no file or directory at ${resolved}. ${listing.length > 0 ? `Nearby files in ${path.dirname(resolved)}:\n${listing.map((name) => `- ${name}`).join("\n")}` : "The parent directory is empty or could not be listed."}`;
+}
+//#endregion
+//#region src/webfetch.ts
+const TIMEOUT_MS = 15e3;
+const BODY_CAP_BYTES = 1e6;
+const TEXT_RETURN_CHARS = 2e4;
+const webfetchTool = {
+	name: "webfetch",
+	description: "Fetch a URL over HTTP(S) and return its content as plain text (HTML tags stripped, no JavaScript rendering). 15 s timeout, 1 MB body cap, first 20 000 chars returned.",
+	inputSchema: {
+		type: "object",
+		properties: { url: {
+			type: "string",
+			description: "Absolute http(s) URL to fetch"
+		} },
+		required: ["url"]
+	},
+	readOnly: true,
+	specifier: (input) => typeof input.url === "string" ? input.url : void 0,
+	handler: async (input) => {
+		const url = typeof input.url === "string" ? input.url : void 0;
+		if (url === void 0 || !URL.canParse(url)) return "Error: the `url` argument is required and must be an absolute http(s) URL.";
+		let response;
+		try {
+			response = await fetch(url, {
+				signal: AbortSignal.timeout(TIMEOUT_MS),
+				redirect: "follow"
+			});
+		} catch (error) {
+			return `Error: fetch failed for ${url}: ${error.message}`;
+		}
+		if (!response.ok) return `Error: ${url} responded with HTTP ${response.status} ${response.statusText}.`;
+		const reader = response.body?.getReader();
+		if (reader === void 0) return `Error: ${url} returned an empty body.`;
+		const decoder = new TextDecoder("utf8", { fatal: false });
+		let text = "";
+		let bytes = 0;
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			bytes += value.byteLength;
+			text += decoder.decode(value, { stream: true });
+			if (bytes >= BODY_CAP_BYTES) {
+				await reader.cancel();
+				text += "\n[body truncated at 1 MB]";
+				break;
+			}
+		}
+		text += decoder.decode();
+		return truncateOutput(((response.headers.get("content-type") ?? "").includes("html") ? htmlToText(text) : text).slice(0, TEXT_RETURN_CHARS), TEXT_RETURN_CHARS);
+	}
+};
+/** Naive HTML → text: drop script/style blocks, strip tags, decode common entities. */
+function htmlToText(html) {
+	return html.replace(/<script[\s\S]*?<\/script>/gi, " ").replace(/<style[\s\S]*?<\/style>/gi, " ").replace(/<!--[\s\S]*?-->/g, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&#0?39;/g, "'").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+}
+//#endregion
+//#region src/write.ts
+const writeTool = {
+	name: "write",
+	description: "Create or overwrite a file. Parent directories are created automatically. Overwriting an existing file with more than 5 lines requires `overwrite: true`.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			path: {
+				type: "string",
+				description: "File path, relative to the project cwd"
+			},
+			content: {
+				type: "string",
+				description: "Full file content to write"
+			},
+			overwrite: {
+				type: "boolean",
+				description: "Set true to overwrite an existing multi-line file"
+			}
+		},
+		required: ["path", "content"]
+	},
+	readOnly: false,
+	specifier: (input) => requireString(input, "path"),
+	handler: async (input, ctx) => {
+		const raw = requireString(input, "path");
+		const content = requireString(input, "content");
+		if (raw === void 0) return "Error: the `path` argument is required and must be a string.";
+		if (content === void 0) return "Error: the `content` argument is required and must be a string.";
+		const resolved = resolveInCwd(ctx.cwd, raw);
+		if ((await stat(resolved).catch(() => null))?.isFile()) {
+			const lines = (await readFile(resolved, "utf8")).split("\n");
+			if (lines.at(-1) === "") lines.pop();
+			const lineCount = lines.length;
+			if (lineCount > 5 && input.overwrite !== true) return `Error: ${resolved} already exists (${lineCount} lines). Overwriting a multi-line file by mistake is hard to undo. If this is intentional, retry with \`overwrite: true\`. For targeted changes prefer the \`edit\` tool.`;
+		}
+		await mkdir(path.dirname(resolved), { recursive: true });
+		await writeFile(resolved, content, "utf8");
+		return truncateOutput(`Wrote ${Buffer.byteLength(content, "utf8")} bytes to ${resolved}`);
+	}
+};
+//#endregion
+//#region src/index.ts
+/** The seven v0.1 built-in tools. */
+function buildTools() {
+	return [
+		readTool,
+		writeTool,
+		editTool,
+		bashTool,
+		globTool,
+		grepTool,
+		webfetchTool
+	];
+}
+//#endregion
+export { MAX_TOOL_OUTPUT_CHARS, bashTool, buildTools, denyReadMessage, editTool, formatNumbered, globTool, grepTool, htmlToText, isDenyReadPath, readTool, requireString, resolveInCwd, truncateOutput, webfetchTool, writeTool };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@chantier/tools",
+  "version": "0.3.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Built-in tools (bash, edit, glob, grep, read, webfetch, write) for the chantier coding agent",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlcassociation/chantier.git"
+  },
+  "homepage": "https://github.com/mlcassociation/chantier#readme",
+  "bugs": {
+    "url": "https://github.com/mlcassociation/chantier/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format esm --dts --clean --out-dir dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@chantier/core": "^0.3.0",
+    "diff": "^8.0.4",
+    "tinyglobby": "0.2.17"
+  },
+  "devDependencies": {
+    "tsdown": "0.23.0"
+  }
+}