[vinniefalco]

The Harness now has three ready-made PromptFinder implementations, so a Host no longer has to write its own closure to serve its prompts. They are in runvil::harness.

This branch sits on top of #17, which is still open. Until #17 merges, the commit list here shows its commit too. The change in this PR is the one commit 67d9d1b4.

Why

Every Host hand-wrote a finder, and the run-prompt example and the test suites each repeated the same one. A Host that keeps its prompts in one or more directories needs a little more than a closure: it has to pick up edits, notice new files, and say what it holds.

What is added

• FindTextPrompt. Serves one prompt, by name, from text given at construction.
• FindFilePrompt. Serves one prompt, by name, from a file. It reads the file with std::fs::read_to_string at each find, so an edit shows in the next find.
• PromptSet. Holds the prompts a Host inserts as text (insert), as a file (insert_file), or as every prompt file in a directory (insert_dir). rescan lists the directories again, and names lists what the set serves.

How PromptSet behaves

• A later insert wins. A find takes the newest insert that has the name. A Host that inserts its shipped directory and then its user's directory serves the user's file under a name both hold.
• Files are read at each find, and nothing is cached. A rescan is only needed for added or removed files, never for edits.
• The Host watches, the set does not. A Host fills the set, shares it behind an Arc, gives one handle to its Host as the finder, and keeps the other to call rescan when it sees a directory change.
• rescan keeps going. A directory that cannot be listed holds no prompt until a later rescan lists it, the others are still listed, and rescan returns one failure for each directory it could not list.
• insert_dir is strict. A directory that cannot be listed is an error and is not kept.
• A prompt file is a regular file directly in the directory whose extension is exactly md and whose name is UTF-8. Its name is its file name, such as greet.md.
• A removed file fails its find with the read's failure until the next rescan. The find does not fall back to an older insert.
• Locking. The inserts take &mut self, so the list of inserts never changes once the set is shared. Each directory's listing has its own lock. A rescan holds it while it lists, and a find holds it only to look a name up and reads the file after.

Failures

Each is the universal Error:

• An unknown name is NotFound, with the message no prompt named {name} and the Name fact.
• A failed read is NotFound, NotUtf8, or Io, with the message prompt {name}: cannot read {path} then the system's reason, and the Name and Path facts.
• A failed listing is NotFound or Io, with the message cannot list prompt directory {path} then the system's reason, and the Path fact.

What else changes

• Facade. runvil::harness re-exports the three types. public-api.txt of runvil gains 20 lines and loses none. The runvil-engine listing does not change.
• Example. run-prompt builds its Host with FindTextPrompt, and its hand-written find function is gone.
• Docs. The crate docs of the runner and of runvil name the stock finders, and the runner has one new invariant: a stock finder reads a file only inside a find, and the Harness calls a finder only from Host::parse, before the run exists.
• Engine. No file of the Engine crates changes, and there is no new dependency.

Tests

prompt_finders-tests.rs has 23 tests:

• Each single finder serves its name, fails any other name, and a file finder fails as NotFound, NotUtf8, or Io.
• The set: which files a directory gives, which insert wins a name, a file read fresh with no rescan, and a missing directory that is refused and not kept.
• Rescan: an added file is found after it, a removed file is forgotten after it, a directory that cannot be listed is reported while the others are listed, and that directory serves its files again once it is back.
• names lists every insert, sorted, each name once, and follows a rescan.
• A Host parses a prompt that its application added to a shared set and rescanned.

Three rules of a listing have no test: a link to a regular file counts as that file, a file name that is not UTF-8 is skipped, and an entry that vanishes during the listing is skipped. The first two need a setup for each platform, and the third needs a test seam.

Checks

Every command in AGENTS.md passes on the final tree, with the run-prompt example, the doc build of runvil alone, and the private-items doc build of runvil-runtime. Nextest runs 3,818 tests, all passing, and skips 24. xtask api --check passes on the pinned nightly.

Plan and findings: plan/2026-11-14-3-stock-prompt-finders.plan.md (see "What the build found").

[coderabbitai]

Caution

Review failed

The pull request is closed.

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[vinniefalco]

Closing: this was opened from a topical branch by mistake. The same commit, 67d9d1b, is now on vinniefalco:master, so it is part of #17.

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge.

Summary

Adds FindTextPrompt, FindFilePrompt, and PromptSet to runvil::harness.

• Runs hold every Pack installed by their Host.
• Each Pack id can belong to only one registered Pack.
• Hosts can serve prompts from text, files, or directories.

No actionable issues found. vinniefalco explicitly documents the broader Pack access and readiness wait as intentional. vinniefalco also acknowledges missing tests for links, non-UTF-8 names, and entries removed during listing.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  App[Application] -->|insert text, files, directories| Set[PromptSet]
  Watcher[Directory watcher] -->|rescan| Set
  Picker[Prompt picker] -->|names| Set
  Host[Host::parse] -->|find| Set
  Set -->|read at each find| Files[Prompt files]
  Host --> Parsed[Parsed prompt]
  Parsed --> Run[Harness run]

Loading

_{Reviews (1) · Last reviewed commit: "Add three stock prompt finders to the Ha..." · Reviewed by Greptile}