// tool-globals.d.ts — generated by axon prepare, do not edit // Every tool the capsule can call, declared as it is callable. // Mirrors the block the model receives — same source, same members. declare global { type MatchLine = { line: number; text: string; isMatch: boolean } type QueryMatch = { path: string; lines?: MatchLine[] } type EditOpError = { kind: "not_found" | "ambiguous_match" | "invalid_operation"; message: string } type EditOpResult = { ok: boolean; count: number; error?: EditOpError } type QueryOpts = { pattern?: string glob?: string /** * DIRECTORY to search under (default: the process cwd). * * A directory, never a file — this is the root of a tree walk, not a * target. Passing a file path is the single most common misuse of this * tool: `cwd` reads as "where to look", a file path is a perfectly * sensible answer to that question, and the underlying glob scan then * fails with a bare `ENOTDIR` that names no parameter and suggests no * fix. Callers hit it repeatedly in one session, corrected by guessing. * * To search inside ONE file, pass its directory here and its name as * `glob` — `{ cwd: "src/app", glob: "index.ts", pattern: "..." }`. To * read a file, use `read()`. */ cwd?: string maxDepth?: number limit?: number context?: number regex?: boolean ignoreCase?: boolean /** * Cap on total lines returned across all matches (default 400). * * `limit` bounds FILES, which is not the same as bounding cost: one file * with forty hits and `context: 2` contributes two hundred lines, so a * hundred files can return tens of thousands. A real run put 244k * characters into the context from one call that looked modest — * `limit: 100, context: 2` — and the wake never recovered. */ maxLines?: number } type QueryResult = { matches: QueryMatch[] /** True when `limit` or `maxLines` cut the result short. */ truncated: boolean total: number /** Set when the LINE budget was what truncated it — the caller should narrow. */ truncatedBy?: "files" | "lines" } // ─── Public types ───────────────────────────────────────────────────────────── export type ReadOpts = { from?: number; to?: number } type Stat = { size: number; isDir: boolean; isFile: boolean; mtime: number } type PatchOpts = { find: string; replace: string; all?: boolean } type PatchResult = { count: number } type EditOp = | { op: "replace"; find: string; replace: string; all?: boolean; occurrence?: number; exact?: boolean } | { op: "insertBefore"; find: string; content: string; occurrence?: number; exact?: boolean } | { op: "insertAfter"; find: string; content: string; occurrence?: number; exact?: boolean } | { op: "delete"; find: string; all?: boolean; occurrence?: number; exact?: boolean } type EditResult = { ok: boolean; ops: EditOpResult[] } const fs: { /** * Search for files by name or content. The primary tool for codebase navigation. * * @param opts.pattern - Text or regex to search in file contents * @param opts.glob - Glob pattern for filename matching (e.g. "**\/*.ts", "*mode*") * @param opts.cwd - DIRECTORY to search under (defaults to process cwd). * A directory, never a file — to search one file, pass its * directory here and its name as `glob`. * @param opts.maxDepth - Max directory traversal depth * @param opts.limit - Max FILES to return (default 50) * @param opts.maxLines - Max total lines across all matches (default 400) * @param opts.context - Lines of context around content matches (default 0) * @param opts.regex - Treat pattern as regex (default false — literal match) * @param opts.ignoreCase - Case insensitive matching (default true) * @returns matches with file paths and matching lines. `truncated` is set when * either cap bit, and `truncatedBy` says which — narrow the pattern * when it reads "lines". * * @example * await fs.query({ pattern: "useMode", glob: "**\/*.ts", context: 2 }) * @example * await fs.query({ glob: "**\/*.vue" }) // find files by name only */ query(opts: QueryOpts): Promise; /** * Read a file. Optionally specify line range for large files. * * @param opts.from - Start line (1-indexed) * @param opts.to - End line (inclusive) * * @example * await fs.read("src/index.ts") * @example * await fs.read("big-file.ts", { from: 50, to: 80 }) */ read(path: string, opts?: ReadOpts): Promise; /** Get file metadata: size, type, modification time. */ stat(path: string): Promise; /** Check if a file or directory exists. */ exists(path: string): Promise; /** List entries in a directory. For searching across the tree, use query() instead. */ list(path: string): Promise; /** Write content to a file, creating or overwriting it. */ write(path: string, content: string): Promise; /** Append content to the end of a file. */ append(path: string, content: string): Promise; /** * Find and replace text within a file without rewriting the whole thing. * * @param opts.find - Exact string to find * @param opts.replace - Replacement string * @param opts.all - Replace all occurrences (default false — first only) * @returns { count } — number of replacements made * * @example * await fs.patch("src/config.ts", { find: "port: 3000", replace: "port: 8080" }) */ patch(path: string, opts: PatchOpts): Promise; /** * Apply multiple targeted edits to a file atomically. * Ops run in order — each sees the result of the previous. * Never rewrites the whole file. Use for inserts, deletes, or multiple changes. * * Ops: * replace — replace the Nth occurrence of find * insertBefore — insert content immediately before the Nth occurrence of find * insertAfter — insert content immediately after the Nth occurrence of find * delete — remove the Nth occurrence of find * * Options (per op): * occurrence — which match to target (default: 1). Ignored when all: true. * all — apply to every match (replace/delete only). * exact — fail with ambiguous_match if find matches more than once. * Use this when the anchor should be unique — safer for destructive ops. * * Each op result: * ok — whether the op succeeded * count — matches found (on failure) or changes made (on success) * error — present on failure: { kind, message } * kind: "not_found" | "ambiguous_match" | "invalid_operation" * * @example * // Add an import and rename a function in one call * const r = await fs.edit("src/index.ts", [ * { op: "insertAfter", find: "import { foo } from './foo'", content: "\nimport { bar } from './bar'" }, * { op: "replace", find: "function oldName(", replace: "function newName(", exact: true }, * ]) * if (!r.ok) console.log(r.ops.filter(o => !o.ok)) * * @example * // Delete a block and replace every TODO comment * await fs.edit("src/utils.ts", [ * { op: "delete", find: "// deprecated\nfunction legacy() {}\n", exact: true }, * { op: "replace", find: "// TODO", replace: "// DONE", all: true }, * ]) */ edit(path: string, ops: EditOp[]): Promise; /** Delete a file. */ remove(path: string): Promise; /** Create a directory (recursive — creates parent dirs as needed). */ mkdir(path: string): Promise; /** Move or rename a file. */ move(from: string, to: string): Promise; /** Copy a file. */ copy(from: string, to: string): Promise; } } export {}

@axon/oma