Rand Stats

MCP::Server::Tool::FileSystem

zef:apogee

Actions Status

MCP::Server::Tool::FileSystem

A root-confined filesystem toolkit for MCP::Server.

Give a model a directory, not a machine. The pack registers eleven tools — read, write, edit, list, glob, grep, map, stat, mkdir, move and delete — and every path argument they take is interpreted relative to a configured root that no argument can escape.

Synopsis

Plug it into a server you are building by hand:

use MCP::Server;
use MCP::Server::Tool::FileSystem;

my $server = MCP::Server.new(:name<workspace>, :version<1.0>);

$server.plug: MCP::Server::Tool::FileSystem.new(root => '/srv/notes');
# Registers fs_read, fs_write, fs_edit, fs_list, fs_glob, fs_grep,
# fs_map, fs_stat, fs_mkdir, fs_move, fs_delete

$server.run;   # stdin/stdout

Or name it in a one-shot server, with no use statement at all — the toolkit is loaded at runtime:

use MCP::Server;

MCP::Server.new(
    :name<workspace>,
    :tools[
        'FileSystem' => { root => '/srv/notes', prefix => 'notes' },
        'FileSystem' => { root => '/srv/logs', prefix => 'logs', 'read-only' => True },
    ],
).run;
# notes_read, notes_write, ... and logs_read, logs_list, logs_glob,
# logs_grep, logs_map, logs_stat

Or skip the Raku entirely and hand raku-mcp a config file:

{
  "name": "workspace",
  "version": "1.0",
  "instructions": "Notes are writable; logs are read-only.",
  "tools": {
    "FileSystem#notes": { "root": "/srv/notes", "prefix": "notes" },
    "FileSystem#logs":  { "root": "/srv/logs", "prefix": "logs", "read-only": true }
  }
}

raku-mcp --config=workspace.json

# Or without a file:
raku-mcp --tool='FileSystem={"root":"/srv/notes"}'

# See what a given configuration would register:
raku-mcp --describe='FileSystem={"root":"/srv/notes"}'

In a Claude Code .mcp.json:

{
  "mcpServers": {
    "notes": {
      "command": "raku-mcp",
      "args": ["--name=notes", "--tool=FileSystem={\"root\":\"/srv/notes\"}"]
    }
  }
}

Configuration

KeyTypeDefaultMeaning
rootIO::PathrequiredDirectory every path is resolved inside. A plain string is coerced. Must exist and be a directory, or construction dies. Stored resolved.
read-onlyBoolFalseWhen True, the write, edit, mkdir, move and delete tools are never registered, and stat reports nothing as writable. The six reading tools — read, list, glob, grep, map and stat — are unaffected.

prefix is reserved by the framework rather than the pack: pass it to .plug as :prefix<...>, or put it beside the toolkit's settings in a :tools entry or config file. Passing it to .new or .from-config dies. Without one, the pack's own default prefix fs applies; an explicit empty prefix registers bare names.

Tools

Names below are unprefixed. With the default prefix they are fs_read, fs_write and so on.

The headings below are the whole signature, and the published JSON Schema says the same thing: a parameter with no = in its heading is in the schema's required array, and a parameter shown as path = '.' carries that value as its JSON Schema default. Both matter more than they look. A schema that marked nothing required would tell a model that read may be called with no path — and a model that believes it (they do) spends its call on an error instead of an answer. A schema that hid the defaults would leave a model unable to tell grep without a path (the whole root) from grep with one.

Parameter naming

Parameter names in this pack are a contract, not a matter of taste:

The reason is what sits in front of the server. A permission layer — Claude Code's directory rules, or MCP::Client::Policy — decides whether a call may go through by looking at which files it would touch, and it finds them by name. A tool that called its argument filename would sail past a rule written for path. If you write a toolkit of your own that is meant to live behind the same guard, use the same names.

Annotations: which tools may run at once

The six reading tools — read, list, glob, stat, grep and map — declare the MCP annotations readOnlyHint => True and idempotentHint => True . The five mutating ones declare nothing.

That is not decoration. A host reads it as a licence to run a batch of those calls side by side and to execute identical calls in one batch once (MCP::Server's execute-tool-calls does exactly that), so it is a claim about the handlers rather than about the intent — and it holds:

Several reads on one pack instance therefore see coherent state. What the annotations do not promise is anything about the filesystem underneath: a read running beside another process's write is a race the pack never had a say in, exactly as it always was.

Ordering is untouched by any of this. A host that batches groups only neighbouring calls, so a write between two reads still means read, write, read.

Structured revisions and conditional mutation

read, list, stat and every successful mutator keep their existing text content and additionally return structuredContent with revisionScheme = sha256-v1. Each location is absent, file, directory, or symlink with an opaque token. File tokens hash exact bytes; directory tokens hash a canonical, path-sorted recursive tree description, so a descendant change changes the directory revision.

The five mutators accept a reserved _expected-revisions object keyed by path, or from/to for move. It is deliberately absent from the advertised schema: an orchestration layer adds it after the model creates the call. When present, every mutation location needs a token. Comparison and the mutation run under one toolkit mutation lock; a mismatch is an isError and does nothing. Calls without the reserved argument retain standalone behaviour.

read(path, offset?, limit?)

Slurps a UTF-8 text file. Errors if the path is missing, is a directory, or is not decodable text.

{ "name": "fs_read", "arguments": { "path": "notes/todo.md" } }
=> "- buy milk\n- feed the yak\n"

With neither offset nor limit, what comes back is the file and nothing else: no numbering, no footer, no line-ending translation. That matters — the text is exactly what edit will be matching against later.

Pass offset (1-based) and/or limit to read a window of a long file instead. Ranged output is a view: each line is prefixed with its number and a tab, and a footer says where the window sits.

{ "name": "fs_read", "arguments": { "path": "log.txt", "offset": 40, "limit": 3 } }
=> "40\tconnecting
    41\thandshake ok
    42\tsending 12 frames

    [lines 40-42 of 900 total]"

Strip the number and the tab before handing any of that text to edit as its old-string — the prefixes are not in the file. Windowed lines are split on line endings and rejoined with \n, so a CRLF file's \rs are not in the windowed output either: before building an old-string for a CRLF file, read it without offset/limit — the unranged form is byte-faithful.

Reading past the end is an answer rather than an error, because that is how a model finds out where the end is:

{ "name": "fs_read", "arguments": { "path": "log.txt", "offset": 5000 } }
=> "'log.txt' has 900 lines; offset 5000 is past the end"

An offset or limit below 1 is an error, as is a non-numeric one. A JSON true is refused rather than read as the number 1, which Raku's type system would otherwise let happen quietly.

write(path, content)

Writes UTF-8 text, replacing any existing contents, and confirms with a byte count. The parent directory must already exist — this tool never creates directories implicitly, so a typo in a path cannot quietly scatter new directory trees. Not registered when read-only is set.

{ "name": "fs_write", "arguments": { "path": "notes/todo.md", "content": "- done\n" } }
=> "Wrote 7 bytes to 'notes/todo.md'"

{ "name": "fs_write", "arguments": { "path": "new/todo.md", "content": "x" } }
=> isError: "Parent directory of 'new/todo.md' does not exist; create it with the mkdir tool first"

edit(path, old-string, new-string, replace-all = false)

Replaces one exact run of text and leaves the rest of the file byte for byte as it was. There is no fuzzy matching and no diff format to get wrong: old-string either appears in the file exactly — whitespace, indentation and line endings included — or the call is an error. Not registered when read-only is set.

{ "name": "fs_edit", "arguments": {
    "path": "src/app.raku",
    "old-string": "my $port = 8080;",
    "new-string": "my $port = %*ENV<PORT> // 8080;" } }
=> "Replaced 1 occurrence in 'src/app.raku'; wrote 412 bytes"

The uniqueness rule is the whole safety story, so it is strict:

An empty new-string deletes the match. Line endings elsewhere in the file are never touched — see Security for why that takes deliberate effort in Raku.

list(path = '.')

One entry per line, sorted, directories marked with a trailing / on every platform. An empty directory answers (empty directory) rather than an empty string.

{ "name": "fs_list", "arguments": { "path": "notes" } }
=> "archive/\nideas.md\ntodo.md"

glob(pattern, path = '.')

Walks everything below path and returns matching paths relative to the root, sorted, one per line.

grep(pattern, path = '.', regex = false, glob?, context = 0, max-results = 50)

Searches the files below path — or path itself, if it names a file — and reports matching lines in GNU grep's format, path:line:text, with paths relative to the root.

{ "name": "fs_grep", "arguments": { "pattern": "TODO", "path": "src" } }
=> "src/app.raku:14:# TODO: retries
    src/lib/db.raku:203:# TODO: index this"

By default the pattern is literal text: no escaping, no surprises, . is a full stop. Set regex to true and it becomes a Raku regex, not a PCRE one. Classes, quantifiers, alternation, anchors and captures read the same; what differs is worth knowing before reaching for it:

The rest of the parameters bound what comes back:

grep is a reading tool: it is registered even when read-only is set. How it searches — and why it would rather have ripgrep pick the files it opens — is How grep searches, below.

How grep searches

grep runs its own scan over its own walk and formats every byte of its own answer. What it will hand to an outside tool — and only when there is one — is the question which files are worth opening at all:

The three tiers return the same bytes. They have to: the external tool never produces a line of the answer, never decides the order, and never sees the glob, the context or the max-results. It answers one question, its answer is used as a filter over the ordinary walk, and everything the model reads is then produced by the same scanner it always was. t/07-grep-parity.rakutest runs every query through every tier installed on the machine and compares the results as strings.

Why

A recursive Raku scan — walk, slurp, decode, split, search — is the heaviest thing in this pack by allocation volume, and several at once reliably tripped a garbage-collector fault in MoarVM 2026.07 that killed the whole process:

MoarVM panic: Heap corruption detected: pointer 0x... to past fromspace

Nothing at the Raku level can catch that — the VM prints one line and calls exit(), so no END block, no LEAVE, no signal handler runs. It is a VM bug rather than this pack's, but a search tool that takes the server down when a model asks two questions at once is this pack's problem. Two measures fixed it at six concurrent searches, and both are in:

What is asked, exactly

rg --files-with-matches --no-config --no-ignore --hidden --no-follow \
   --no-messages --text --fixed-strings -- <pattern> <absolute directory>

grep -r -l -F -a -s -- <pattern> <absolute directory>

Every flag is there to make the searcher's idea of "worth opening" a superset of the scan's. --no-ignore because a .gitignore is not this pack's filter (the root is); --hidden because the walk does not skip dotfiles; --no-follow because it does not descend symlinked directories; --text and -a because a binary file must still be listed — dropping it is the scan's decision, taken on the same NUL sniff as always; --no-config because a user's rg configuration file must not be able to change what a tool call returns. The searcher runs with LC_ALL=C and without GREP_OPTIONS, GREP_COLORS or RIPGREP_CONFIG_PATH.

The glob parameter is deliberately not passed on: its dialect is this pack's, not ripgrep's, and the scan applies it. Neither searcher's own file list is used for paths or for order, either — their idea of sorted (a/b before a.txt) is not the walk's (a before a.txt, then descend).

Two kinds of file are opened whatever the searcher said about them, because its silence cannot mean anything: a symlink (no searcher follows one it meets during a traversal, while this pack reads one whose target is inside the root) and a name carrying a line break (which cannot be found in a list that arrives one path per line).

What never leaves Raku

The probe, and how long it is remembered

A searcher counts as usable only once it has actually run and answered --version. That costs a process spawn, so the verdict is taken once per binary per process and never revisited — the "no" as firmly as the "yes", since paying a failed spawn on every search would cost more than the tier saves. "No" means the binary is not there, or that it ran and gave no version: exited non-zero, or printed nothing. A probe that gets no answer at all is not a verdict, and is not kept: a binary that is there but could not be launched — the server out of file descriptors, the system out of processes, the binary being rewritten by an upgrade — or one killed by a signal before it replied is asked again on the next call. A searcher that passed its probe and later cannot be launched is looked for the same way: if its binary has gone, it is dropped there and then, as if its probe had said no, and the searches after it spawn nothing; if it is still there, the failure is the moment's, the next search tries again, and it is not held against the searcher.

Which answers are believed

After the probe, each search decides whether its own answer can be believed. One that cannot costs that search a full scan and not the tier — until a searcher has given five in a row with no believed answer between them, which drops it as a failed probe would. One bad answer is as likely to be the moment (an OOM-killed child, an unlucky list) as the tool, and giving a searcher up over it would leave a long-running server slow for the rest of its life; five in a row is the tool, and hundreds of searches should not each pay a spawn and a scan for it. A believed answer starts the count again, and a launch that failed while the binary was there never counts. An answer is believed when the searcher was not killed by a signal and exited with a status its documentation calls an answer. ripgrep's man page gives 0 for a match, 1 for none and 2 for an error; GNU grep's gives the same three; BSD grep's and POSIX's give 0, 1, and anything above 1 for an error. So:

Measured on ripgrep 14.1.1, GNU grep 3.12 and BSD grep 2.6.0: an unreadable file or directory exits 2 with every readable match listed and stderr empty, and an unknown option exits 2 with nothing listed and a message on stderr.

The consequence worth stating plainly: installing rg while a server is running does not speed up that server, only the next one — unless whatever hosts the pack calls reset-searchers, below.

Overriding it

VariableValueEffect
MCP_FS_GREP_BACKENDauto (default)ripgrep if it is there, else a system grep, else the Raku scan
MCP_FS_GREP_BACKENDripgreponly ripgrep; the Raku scan when it is unusable
MCP_FS_GREP_BACKENDgreponly a system grep; the Raku scan when it is unusable
MCP_FS_GREP_BACKENDrakunever shell out
MCP_FS_GREP_RG_BINARYa binary name or pathwhat the ripgrep tier spawns; defaults to rg
MCP_FS_GREP_GREP_BINARYa binary name or pathwhat the grep tier spawns; defaults to grep

Any other value of MCP_FS_GREP_BACKEND is an error on the call rather than a silent fallback, so a typo cannot quietly cost a tier.

They exist for the parity tests, which have to pin a search to a tier they choose, and they are read on every call rather than cached. The binary overrides must name the real tool: a searcher that runs happily and prints something else cannot be detected, only believed.

Re-checking the searchers

Everything the pack learns about the searchers — every probe verdict, the "yes" and the "no" alike, every searcher dropped, every count of answers that could not be believed — lasts for the life of the process. MCP::Server::Tool::FileSystem::reset-searchers() forgets all of it, so the next search probes again from scratch: a ripgrep installed since the first search is found, and a searcher dropped in error is given its chance back.

our sub reset-searchers(--> Nil)

It is a library function rather than a tool, because whether the host's programs have changed is the host's question, not the model's. It is process-wide, like the state it clears, which every pack instance in the process shares. It is safe to call while searches are running — a search already under way finishes on what it had — and safe to call again, since clearing nothing changes nothing. It leaves MCP_FS_GREP_BACKEND alone; that is read on every search anyway.

A harness that serves the pack to a user is the natural caller: bind it to a command, so the user can say "I have just installed ripgrep" without restarting anything.

use MCP::Server::Tool::FileSystem;

# One entry in a harness's own command table.
my %commands = rescan => {
    MCP::Server::Tool::FileSystem::reset-searchers();
    'The next search looks for ripgrep and a system grep again.';
};

# ...and when the user types /rescan:
say %commands<rescan>();

The notice that is gone

grep used to end an answer that had skipped unreadable files with

[skipped 2 files that are not UTF-8 text]

That line has been removed. Ripgrep passes a binary file over in silence and cannot be made to count them, so the notice was the one part of the output that could not survive the question "which tier served this call?". Identical answers are worth more than the count was. The other notice — [stopped at N matching lines; raise max-results to see more] — is unchanged: every tier reproduces it, because every tier counts the same matched lines.

map(path = '.', query?, focus?, max-chars = 8192)

Returns a ranked skeleton of the code below path: the files that matter, each as its path followed by the definition lines of its most-referenced symbols. Bodies never appear. It is the tool to reach for before reading anything, and it is the reason not to read twenty files to find the two that matter.

{ "name": "fs_map", "arguments": { "path": "src" } }
=> "src/hub.py:
      12: def frobnicate(value):
    ⋮
      48: class Dispatcher:

    src/cli.py:
       7: def main(argv):

    [mapped 2 files (1 skipped: unsupported/binary/too-large), 3 definitions; ranked by references]"

Line numbers are 1-based and pair with read's offset, so a definition worth reading is one call away. A ⋮ marks a gap between printed lines, so nothing reads as adjacent that is not.

Ranking is a personalized PageRank over the graph "file A refers to something file B defines". A file is important because the rest of the tree leans on it — not because it is large, and not because it sorts early. Two parameters steer the walk:

Which definitions of a chosen file get printed is a second, separate question, and the answer is not simply "the most referenced". A name's references are shared among the files that define it, and a name that most of the map refers to is set aside altogether. Both rules exist because references are matched by name and nothing else: in a 131-file application, new was declared three times and called twelve hundred times, so a naive count made method new the one line printed for three unrelated files. Under these rules each of those files is represented by its own class declaration instead, while a symbol that only a handful of files mention — which is what a symbol worth reading looks like — keeps its full weight.

max-chars (512 to 65536, default 8192) bounds the answer. The budget is spent whole files at a time: when the map does not fit, every file loses its least-referenced definitions first, and whatever still does not fit is dropped as a block rather than cut off mid-file. A half-printed file would invite exactly the mistake the tool exists to prevent — reading a signature that is not really there. The summary line is always last and always present, and says what was left out.

Languages, and how they are read:

.git, node_modules, target, build, dist, vendor, __pycache__, virtualenvs and every dot-directory are never descended into: a vendored copy of a library outranks the code that uses it, which makes for a confident and useless map. The walk stops after 5000 files and says so.

Parse results are cached per file, keyed on modification time and size, for the lifetime of the toolkit instance — so mapping, editing one file and mapping again re-reads exactly that file. The cache is not bounded and is not written to disk.

map is a reading tool: it is registered even when read-only is set.

stat(path)

{ "name": "fs_stat", "arguments": { "path": "notes/todo.md" } }
=> "path: notes/todo.md
    type: file
    size: 26
    modified: 2026-07-29T20:14:02Z
    symlink: no
    readable: yes
    writable: yes"

type is file, directory or other; modified is ISO 8601 in UTC; writable is always no on a read-only pack, whatever the mode bits say, because no tool in that configuration can write.

mkdir(path)

Creates a directory and any missing parents. Creating one that already exists is a no-op, not an error, so a model retrying itself does not get punished. Not registered when read-only is set.

{ "name": "fs_mkdir", "arguments": { "path": "notes/archive/2026" } }
=> "Created directory 'notes/archive/2026'"

move(from, to)

Renames a file or directory, or moves it somewhere else inside the root. Both from and to go through the same containment checks, so neither end can leave the sandbox. A directory moves with everything inside it. Not registered when read-only is set.

{ "name": "fs_move", "arguments": { "from": "notes/todo.md", "to": "notes/archive/todo.md" } }
=> "Moved 'notes/todo.md' to 'notes/archive/todo.md'"

Nothing is ever overwritten and nothing is created implicitly:

There is no copy-and-delete fallback across filesystems: the move is a rename, and a rename that the OS refuses (a to on a different mount, say) is reported as the error it is rather than half-performed. See Security.

delete(path, recursive = false)

Deletes a file, or a directory that is empty. Not registered when read-only is set.

{ "name": "fs_delete", "arguments": { "path": "notes/scratch.md" } }
=> "Deleted file 'notes/scratch.md'"

{ "name": "fs_delete", "arguments": { "path": "notes/empty" } }
=> "Deleted empty directory 'notes/empty'"

{ "name": "fs_delete", "arguments": { "path": "notes/archive" } }
=> isError: "Directory 'notes/archive' is not empty; set recursive to true to
   delete it and everything below it"

recursive is rm -rf and nothing less: the directory and every file below it go, with no undo and no confirmation step.

{ "name": "fs_delete", "arguments": { "path": "notes/archive", "recursive": true } }
=> "Deleted directory 'notes/archive' and everything below it"

Symlinks are deleted as the links they are, never followed — a recursive delete of a directory containing a link to somewhere else removes the link and leaves its target alone. Deleting the root itself is refused.

Errors

Handlers throw; the framework turns that into a tool result with isError: true and the message as its text, so the model sees what went wrong and can correct itself. Missing or non-string arguments are reported the same way — the MCP input schema advertises what is required, but nothing in the protocol enforces it.

Security

Confinement is the whole point of this pack, so it is done in layers that each hold on their own. For a path argument $rel:

The textual rejections are deliberately redundant with the physical check: two independent layers fail independently, and they make the failure message say what the model did wrong.

Path-component comparison is exact-case. On a case-insensitive filesystem, a root configured with different casing than the path the OS reports can only produce a false negative — access denied — never a false positive. It fails closed.

Byte fidelity, and why CRLF is a security property

read and edit never see a decoded-and-re-encoded copy of your file: they read bytes and decode them once, and edit writes bytes back.

This is deliberate, and it took work. Raku's IO::Path.slurp in text mode silently folds CRLF into LF, and .spurt does not put it back. An edit that round-tripped through the text path would therefore rewrite the line endings of every line in the file it did not touch — a one-line change arriving as a whole-file diff. On a CRLF checkout that is not a cosmetic problem: it is an invisible, unreviewable change to code, made by a tool the reviewer trusts to change one line.

So the guarantee is: edit changes the bytes you asked it to change and no others, and the text read hands back is what edit will be matching against, byte for byte. The cost is that an old-string copied out of a CRLF file must carry its CRLF; the alternative was silent corruption.

Regex interpolation

grep's regex mode interpolates the client's pattern into a real Raku regex (/<$pattern>/). That is only safe because Rakudo refuses, by default, to interpolate a pattern containing a code block — a pattern like { unlink 'x' } is rejected with Prohibited regex interpolation rather than executed. The refusal comes back to the model as an ordinary tool error.

Never add use MONKEY-SEE-NO-EVAL to this file. That pragma exists to turn exactly this guard off, and turning it off here converts a search tool into remote code execution. The module carries a comment saying so, and t/02-tools.rakutest asserts that an injection pattern comes back as a clean error — that test is the guard on the guard.

Malformed patterns are validated before the walk starts, so a bad pattern costs one clear error rather than a partial traversal.

Residual risks worth knowing:

Resolving a path the way the OS will

The resolver behind containment is public, for any code that has to name a directory where the operating system will check it: a sandbox profile that lists the paths a child may write, a lock keyed on a path, a "which root is this under" test of your own.

use MCP::Server::Tool::FileSystem;

my &physical = &MCP::Server::Tool::FileSystem::physical-path;

# /srv/current -> releases/42
say physical('/srv/current/notes.txt'.IO);   # "/srv/releases/42/notes.txt".IO

# C:\Users\me\work is a junction to D:\work
say physical('C:\Users\me\work\src'.IO);     # "D:/work/src".IO

# Paths that do not exist yet are kept as far as they go.
say physical('/srv/current/not/yet'.IO);     # "/srv/releases/42/not/yet".IO

physical-path(IO::Path:D $path, Int:D :$max-hops = 40 --> IO::Path:D) makes $path absolute against $*CWD, then walks it one component at a time. Every component that is a link — a symlink anywhere, and on Windows a junction too — is replaced by its target and the walk carries on from there, so a link in the middle of a path is followed just like one at the end. The result is absolute and link-free as far as the path exists. Windows paths come back with an upper-case drive letter; .absolute gives the native spelling.

Why not IO::Path.resolve

.resolve is the right tool on POSIX and the wrong one on Windows. It does not follow symbolic links there, and when it meets a junction it splices the junction's absolute target onto the junction's parent and returns a path that does not exist. physical-path is one implementation on every platform.

.. follows the platform's rule

The two families disagree about what .. means once a link is involved, and the resolver has to agree with the OS it runs on, or a path the check calls inside is one the OS opens outside. Take one/L/../x.txt, where L is a link to deep/a/b:

t/10-physical-path.rakutest reads each such path through the OS and checks that physical-path names the file the OS opened.

Failing closed

physical-path dies rather than guess when:

A containment check with it

Resolve both sides, then compare. Resolving only the candidate means a root reached through a link never matches:

my $root = physical($workspace.IO).absolute;
my $p    = physical($candidate.IO).absolute;
my $sep  = $*SPEC.dir-sep;
die "outside the workspace: $candidate"
    unless $p eq $root || $p.starts-with($root.ends-with($sep) ?? $root !! $root ~ $sep);

The comparison is exact-case, so on a case-insensitive filesystem a mismatch in case denies rather than admits. What a resolver cannot defend against is the filesystem changing after the check: resolve, check and open as close together as you can.

Testing

prove6 -Ilib t/           # with MCP::Server installed
prove6 -Ilib -I../MCP-Server/lib t/    # against a sibling checkout

t/03-containment.rakutest is the file to read first if you change the resolver: it drives every escape attempt through real tool calls, including symlink escapes, and adapts rather than skips on hosts where creating a symlink is not permitted. t/10-physical-path.rakutest pins the resolver itself: it reads each tricky path through the OS and demands that physical-path names the file the OS opened, using junctions on Windows so that it needs no privilege there. t/05-map.rakutest is the one to read if you change the map: it builds a small polyglot tree whose ranking has one right answer and asserts that answer, rather than asserting that some map came back.

t/07-grep-parity.rakutest is the one to read if you touch grep. It runs every kind of query through every searcher installed on the machine and asserts the answers are identical strings, skipping an arm only when its binary genuinely is not there and saying which. t/08-grep-backend.rakutest covers the tier choice itself — that a searcher is probed once, that a probe which got no answer is asked again, and that a search believes only an answer the searcher's documentation calls one: stand-in searchers it writes for itself exit 3, die by a signal part-way through their list, refuse with a message or fail in silence, and the answer and the spawn count show which lists were believed, that a searcher is given up only when its binary has gone or after five untrusted answers in a row, and that reset-searchers brings every one back. t/07 holds the real tools to the same rule with a file in the root that nobody may read. t/11-handles.rakutest holds every tool to giving back every file descriptor it takes: it counts the handles the process holds open — from the kernel's own list on Linux and macOS, with GetProcessHandleCount on Windows — around a few hundred calls, and runs a hundred searches in a row without losing the external searcher.

Examples

Author

Matt Doughty

License

Artistic-2.0