pi-jev-find 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 pi-jfind contributors
+
+Portions derived from:
+- oh-my-pi (https://github.com/can1357/oh-my-pi), MIT License (c) 2025 Can Bölük —
+  the jfind cascade (packages/coding-agent/src/tools/jfind).
+- jegrep (https://github.com/can1357/jegrep), MIT License (c) 2026 Can Bölük —
+  the cascade budget design.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# pi-jev-find
+
+A semantic **find** tool for the [pi coding agent](https://github.com/earendil-works/pi-coding-agent) — a standalone port of the [oh-my-pi](https://github.com/can1357/oh-my-pi) `jfind` cascade (itself derived from [jegrep](https://github.com/can1357/jegrep)).
+
+`find` answers *"where does this codebase implement X?"* in one call: a four-stage cascade (lexical scan → filename ranking → passage judging → full-file verification) that uses ripgrep for the cheap stages and the **Jev** probability API ([TypeSafe System One](https://typesafe.ai)) for judgment, returning calibrated line ranges instead of keyword soup.
+
+The judge is the native System One API — the same wire jegrep uses — so probabilities are absolute and calibrated, not emulated through a chat model.
+
+## Install
+
+```sh
+pi install npm:pi-jev-find
+```
+
+or in a single project, copy/symlink `src/` under `.pi/extensions/` and run `/reload`.
+
+Requires `rg` (ripgrep) on your `PATH`.
+
+## What the model sees
+
+```
+find(query: "where do we validate webhook signatures?", max: 8)
+→
+src/billing/webhooks.ts
+  41-89  0.94  hmac verification + timestamp tolerance
+  212-248 0.71  retry queue re-checks signature on replay
+src/lib/crypto/sign.ts
+  ...
+```
+
+Each hit carries judge-calibrated probabilities; ranges are exact line spans, ready for a follow-up `read`.
+
+## Configuration
+
+All knobs are environment variables; all are optional except the API key.
+
+### Judge endpoint
+
+| Variable | Fallback (jegrep-compatible) | Default | Meaning |
+| --- | --- | --- | --- |
+| `JEV_API_KEY` | `TYPESAFE_API_KEY` | — (required) | Bearer key for the System One API. |
+| `JEV_BASE_URL` | `TYPESAFE_BASE_URL` | `https://api.typesafe.ai` | API root. |
+| `JEV_MODEL` | `TYPESAFE_DEFAULT_MODEL` | `jev-latest` | Judgment model. |
+
+### Cascade budgets
+
+| Variable | Default | Meaning |
+| --- | --- | --- |
+| `JF_ENABLED` | `1` | `0` disables the tool registration entirely. |
+| `JF_CANDIDATES` | `128` | Max candidate files kept after the lexical scan. |
+| `JF_FILES` | `20` | Max files whose names are judged. |
+| `JF_WINDOWS` | `24` | Max passage windows judged per file. |
+| `JF_WINDOW_BYTES` | `8192` | Passage window size in UTF-8 bytes. |
+| `JF_SKETCH_BYTES` | `384` | Bytes per file sketch shown to the filename judge. |
+| `JF_FULL_LIMIT` | `40` | Max files read fully in the verification stage. |
+| `JF_CONCURRENCY` | `16` | Parallel judge requests. |
+
+Run `/find` inside pi to see the resolved judge endpoint and budgets.
+
+## How it works
+
+```
+query ──► keywords (stopword split, camelCase split)
+      ──► rg -i --json          lexical scores: idf-weighted hit counts   (CANDIDATES=128)
+      ──► rg --files + filters  deny dirs, secrets, binaries             (FILES=20)
+      ├─ stage 1: filename judge  "is <sketch of path> likely to contain <intent>? 0..1"
+      ├─ stage 2: passage judge   per 8 KB window, line ranges + p
+      └─ stage 3: full-file verify top hits, merge ranges
+      ──► ranked hits with line ranges + probabilities
+```
+
+- Budgets mirror jegrep's published defaults; every request is one batched System One call, so a typical find costs a few cents at most.
+- Secret files (`.env`, keys, pem, tfstate…) and VCS dirs never reach the judge.
+- Lexical champions (top-2 files by keyword score) skip judging and are read directly.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Derived from oh-my-pi's `jfind` (MIT, Can Bölük) and jegrep (MIT, Can Bölük).

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "pi-jev-find",
+	"version": "0.1.0",
+	"description": "Semantic find tool for the pi coding agent — a cascade-search port of jegrep / oh-my-pi jfind",
+	"type": "module",
+	"license": "MIT",
+	"main": "src/index.ts",
+	"files": [
+		"src",
+		"LICENSE",
+		"README.md"
+	],
+	"keywords": [
+		"pi",
+		"pi-extension",
+		"semantic-search",
+		"ripgrep",
+		"jev",
+		"typesafe",
+		"code-search"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/TengYangTuoHai/pi-jev-find.git"
+	},
+	"scripts": {
+		"test": "bun test",
+		"typecheck": "tsc --noEmit"
+	},
+	"dependencies": {
+		"typebox": "^1.3.27"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "^0.87.0",
+		"@earendil-works/pi-tui": "^0.87.0",
+		"@types/bun": "^1.3.0",
+		"typescript": "^5.9.0"
+	},
+	"pi": {
+		"extensions": ["src/index.ts"]
+	}
+}

package/src/cascade/cascade.ts

@@ -0,0 +1,357 @@
+/**
+ * Cascade search: semantic passage maps before full-source reading.
+ *
+ * 1. Lexical scan ranks every eligible file by query keywords.
+ * 2. Filename ranking judges the top candidates by name and place in the tree.
+ * 3. Passage scoring reads the strongest files, cuts them into byte-bounded
+ *    windows, and judges a budgeted verbatim sketch of each window.
+ * 4. Verification judges the complete text of the sketches that survived.
+ *
+ * Sketch judgments are only routing signals: a reported heat range always
+ * comes from a complete passage. Each judged phase runs its requests through
+ * a bounded-parallel dispatcher and drains fully before the next begins, so
+ * the critical path is three dependent waves.
+ *
+ * Ported from oh-my-pi `packages/coding-agent/src/tools/jfind/cascade.ts`
+ * (MIT): local judge/types instead of `@oh-my-pi/pi-ai`, local FindHit /
+ * FindStats instead of `@oh-my-pi/pi-tui`, budgets injectable via options,
+ * and a local `throwIfAborted`.
+ */
+import * as path from "node:path";
+import type { Budgets } from "../config.ts";
+import { DEFAULT_BUDGETS } from "../config.ts";
+import type { Judge, JudgmentResult } from "../judge/types.ts";
+import type { FindHit, FindStats } from "../types.ts";
+import { fileScore, grepIndex, idf } from "./lexical.ts";
+import { keywords as deriveKeywords } from "./keywords.ts";
+import { type HeatRange, mergeHeat, type Passage, plainContent, selectWindows, sketch, windows } from "./passages.ts";
+import { nameBatch, passageBatch, passageKey, entryKey, type Request, type SketchCard, sketchBatch } from "./questions.ts";
+import { lines, readText, ReadTextError, takeChars } from "./text.ts";
+import { type FileEntry, listFiles } from "./tree.ts";
+
+/** Sketch probability below which a passage is not verified. */
+const CUTOFF = 0.45;
+/** Verified-passage probability at or above which a file is a hit. */
+const THRESHOLD = 0.2;
+/** Bytes of a file read for windowing. */
+const READ_LIMIT = 4 * 1024 * 1024;
+/** Sketch state budget per request; sized so cards stay well inside the judge's context. */
+const SKETCH_STATE_BYTES = 18_000;
+/** Hard cap on sketch cards per request. */
+const SKETCH_CARDS_MAX = 48;
+/** Passage state budget per verification request, tags included. */
+const VERIFY_STATE_BYTES = 24 * 1024;
+/** Wall-clock budget for the lexical scan. */
+const SCAN_TIMEOUT_MS = 30_000;
+/** Distinct failure messages retained for the report. */
+const FAILURES_KEPT = 5;
+
+export interface CascadeOptions {
+	root: string;
+	query: string;
+	/** Caller-supplied lexical keywords, added to those derived from the query. */
+	extraKeywords: readonly string[];
+	judge: Judge;
+	includeHidden: boolean;
+	/** Cascade budgets; defaults mirror the reference implementation. */
+	budgets?: Budgets;
+	signal?: AbortSignal;
+	onProgress?: (message: string) => void;
+}
+
+export interface CascadeResult {
+	/** Files whose verified passages cleared the threshold, strongest first. */
+	hits: FindHit[];
+	threshold: number;
+	keywords: string[];
+	stats: FindStats;
+}
+
+interface FilePlan {
+	node: number;
+	total: number;
+	truncated: boolean;
+	passages: Passage[];
+}
+
+type Answers = JudgmentResult;
+type Outcome = { ok: true; result: Answers } | { ok: false; error: unknown };
+
+/** Throw the signal's abort reason, mapped to a plain DOM abort error when absent. */
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw new DOMException("aborted", "AbortError");
+}
+
+/** A finite probability, or `undefined` when the judge produced nothing usable for the key. */
+function noul(outcome: Outcome, key: string): number | undefined {
+	if (!outcome.ok) return undefined;
+	const p = outcome.result.answers[key]?.noul;
+	return p !== undefined && Number.isFinite(p) && p >= 0 && p <= 1 ? p : undefined;
+}
+
+function chunks<T>(items: readonly T[], size: number): T[][] {
+	const out: T[][] = [];
+	for (let start = 0; start < items.length; start += size) out.push(items.slice(start, start + size));
+	return out;
+}
+
+function compareRel(a: FileEntry, b: FileEntry): number {
+	return a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0;
+}
+
+class Cascade {
+	readonly #options: CascadeOptions;
+	readonly #budgets: Budgets;
+	readonly stats: FindStats = {
+		filesListed: 0,
+		requests: 0,
+		errors: 0,
+		judged: 0,
+		filesRead: 0,
+		fileBytes: 0,
+		inputTokens: 0,
+		outputTokens: 0,
+		cost: 0,
+		apiMs: 0,
+		windowsJudged: 0,
+		windowsPruned: 0,
+		mapCards: 0,
+		failures: [],
+	};
+
+	constructor(options: CascadeOptions) {
+		this.#options = options;
+		this.#budgets = options.budgets ?? DEFAULT_BUDGETS;
+	}
+
+	#fail(phase: string, error: unknown): void {
+		const message = `${phase}: ${error instanceof Error ? error.message : String(error)}`;
+		const { failures } = this.stats;
+		if (failures.length < FAILURES_KEPT && !failures.includes(message)) failures.push(message);
+	}
+
+	async #ask(request: Request): Promise<Outcome> {
+		const { judge, signal } = this.#options;
+		const started = performance.now();
+		try {
+			const result = await judge.judge(request, { signal });
+			this.stats.requests++;
+			this.stats.apiMs += performance.now() - started;
+			this.stats.inputTokens += result.usage.input;
+			this.stats.outputTokens += result.usage.output;
+			this.stats.cost += result.usage.cost;
+			return { ok: true, result };
+		} catch (error) {
+			throwIfAborted(signal);
+			this.stats.requests++;
+			this.stats.errors++;
+			this.stats.apiMs += performance.now() - started;
+			return { ok: false, error };
+		}
+	}
+
+	/**
+	 * Run every job with at most `budgets.concurrency` requests in flight, handing
+	 * each outcome to `settle` in completion order. Resolves once the queue drains.
+	 */
+	async #dispatch<J extends { request: Request }>(jobs: readonly J[], settle: (job: J, outcome: Outcome) => void) {
+		let next = 0;
+		const worker = async () => {
+			while (next < jobs.length) {
+				throwIfAborted(this.#options.signal);
+				const job = jobs[next++]!;
+				settle(job, await this.#ask(job.request));
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(this.#budgets.concurrency, jobs.length) }, worker));
+	}
+
+	async run(): Promise<CascadeResult> {
+		const { root, query, includeHidden, signal, onProgress } = this.#options;
+		const budgets = this.#budgets;
+		const keywords = deriveKeywords(query, this.#options.extraKeywords);
+
+		onProgress?.("lexical scan");
+		const [entries, index] = await Promise.all([
+			listFiles(root, { includeHidden, signal }),
+			grepIndex(root, keywords, { includeHidden, signal, timeoutMs: SCAN_TIMEOUT_MS }),
+		]);
+		this.stats.filesListed = entries.length;
+		const weights = idf(index);
+		const noCounts = Array.from({ length: keywords.length }, () => 0);
+		const ranked = entries
+			.map((entry, node) => ({
+				node,
+				lex: fileScore(index.perFileKw.get(entry.rel) ?? noCounts, weights, entry.rel, keywords),
+			}))
+			.sort((a, b) => b.lex - a.lex || compareRel(entries[a.node]!, entries[b.node]!))
+			.slice(0, budgets.candidates);
+		const nameScore = Array.from<number | undefined>({ length: entries.length });
+
+		// Wave 1: filename ranking over the lexical shortlist.
+		const project = path.basename(root);
+		const nameJobs = chunks(
+			ranked.map(candidate => candidate.node),
+			budgets.nameBatch,
+		).map(batch => ({
+			batch,
+			request: nameBatch(
+				project,
+				query,
+				batch.map(node => entries[node]!),
+			),
+		}));
+		let named = 0;
+		onProgress?.(`filename ranking 0/${ranked.length}`);
+		await this.#dispatch(nameJobs, (job, outcome) => {
+			named += job.batch.length;
+			if (!outcome.ok) this.#fail("filenames", outcome.error);
+			job.batch.forEach((node, k) => {
+				const p = noul(outcome, entryKey(k));
+				nameScore[node] = p;
+				if (p === undefined) {
+					if (outcome.ok) this.stats.errors++;
+				} else {
+					this.stats.judged++;
+				}
+			});
+			onProgress?.(`filename ranking ${named}/${ranked.length}`);
+		});
+
+		// The two strongest lexical candidates are read regardless of the name
+		// judgment; the rest of the budget follows name score, then lexical rank.
+		const selected = ranked.slice(0, Math.min(budgets.files, 2)).map(candidate => candidate.node);
+		ranked.sort((a, b) => (nameScore[b.node] ?? 0) - (nameScore[a.node] ?? 0) || b.lex - a.lex);
+		for (const candidate of ranked) {
+			if (selected.length >= budgets.files) break;
+			if (!selected.includes(candidate.node)) selected.push(candidate.node);
+		}
+		onProgress?.(`reading ${selected.length} files`);
+		const plans = await Promise.all(
+			selected.map(async (node): Promise<FilePlan | undefined> => {
+				const entry = entries[node]!;
+				try {
+					const read = await readText(entry.path, READ_LIMIT);
+					const passages = selectWindows(windows(read.text, budgets.windowBytes, keywords, weights), budgets.windows);
+					if (passages.length === 0) return undefined;
+					return { node, total: lines(read.text).length, truncated: read.truncated, passages };
+				} catch (error) {
+					// Binary and blank files are expected misses, not failures worth reporting.
+					if (!(error instanceof ReadTextError) || error.kind === "io") this.#fail(`read ${entry.rel}`, error);
+					return undefined;
+				}
+			}),
+		);
+		const files = plans.filter((plan): plan is FilePlan => plan !== undefined);
+
+		// Wave 2: sketch routing over mixed-file cards.
+		const cards: { f: number; p: number }[] = [];
+		files.forEach((plan, f) => plan.passages.forEach((_, p) => cards.push({ f, p })));
+		let sketchSentBytes = 0;
+		const sketchJobs = chunks(
+			cards,
+			Math.min(SKETCH_CARDS_MAX, Math.max(1, Math.floor(SKETCH_STATE_BYTES / budgets.sketchBytes))),
+		).map(batch => {
+			const sketches: SketchCard[] = batch.map(({ f, p }) => {
+				const text = sketch(files[f]!.passages[p]!, keywords, weights, budgets.sketchBytes);
+				sketchSentBytes += Buffer.byteLength(text);
+				return { fileKey: `f${f}`, rel: entries[files[f]!.node]!.rel, sketch: text };
+			});
+			return { batch, request: sketchBatch(query, sketches) };
+		});
+		this.stats.mapCards += cards.length;
+		onProgress?.(`scoring ${cards.length} passage sketches across ${files.length} files`);
+		const candidates: { f: number; p: number; score: number }[] = [];
+		await this.#dispatch(sketchJobs, (job, outcome) => {
+			if (!outcome.ok) this.#fail("sketches", outcome.error);
+			job.batch.forEach(({ f, p }, k) => {
+				const score = noul(outcome, passageKey(k));
+				if (score === undefined && outcome.ok) this.stats.errors++;
+				// Failure is unknown, never grounds for a negative judgment.
+				candidates.push({ f, p, score: score ?? 1 });
+			});
+		});
+		candidates.sort(
+			(a, b) =>
+				b.score - a.score ||
+				files[b.f]!.passages[b.p]!.score - files[a.f]!.passages[a.p]!.score ||
+				compareRel(entries[files[a.f]!.node]!, entries[files[b.f]!.node]!) ||
+				files[a.f]!.passages[a.p]!.start - files[b.f]!.passages[b.p]!.start,
+		);
+		const survivors = candidates.filter(candidate => candidate.score >= CUTOFF).slice(0, budgets.fullLimit);
+		this.stats.windowsPruned += cards.length - survivors.length;
+		const chosen = new Map<number, number[]>();
+		for (const { f, p } of survivors) {
+			const list = chosen.get(f);
+			if (list) list.push(p);
+			else chosen.set(f, [p]);
+		}
+
+		// Wave 3: verification of complete passages, grouped per file.
+		const verifyJobs: { f: number; passages: Passage[]; request: Request }[] = [];
+		for (const f of [...chosen.keys()].sort((a, b) => a - b)) {
+			const rel = entries[files[f]!.node]!.rel;
+			const ps = chosen.get(f)!.sort((a, b) => a - b);
+			for (const group of chunks(ps, Math.max(1, Math.floor(VERIFY_STATE_BYTES / budgets.windowBytes)))) {
+				const passages = group.map(p => files[f]!.passages[p]!);
+				verifyJobs.push({ f, passages, request: passageBatch(query, rel, passages) });
+			}
+		}
+		onProgress?.(`verifying ${survivors.length} passages in ${chosen.size} files`);
+		const results = new Map<number, { score: number; heat: HeatRange[]; lines: number; bytes: number }>();
+		await this.#dispatch(verifyJobs, (job, outcome) => {
+			if (!outcome.ok) {
+				this.#fail("verification", outcome.error);
+				return;
+			}
+			let entry = results.get(job.f);
+			if (!entry) {
+				entry = { score: 0, heat: [], lines: 0, bytes: 0 };
+				results.set(job.f, entry);
+			}
+			job.passages.forEach((passage, k) => {
+				const score = noul(outcome, passageKey(k));
+				if (score === undefined) {
+					this.stats.errors++;
+					return;
+				}
+				const text = plainContent(passage);
+				entry.score = Math.max(entry.score, score);
+				entry.heat.push({
+					start: passage.start,
+					end: passage.end,
+					p: score,
+					snippet: takeChars(lines(text).find(line => line.trim().length > 0) ?? "", 100),
+				});
+				entry.lines += passage.end - passage.start + 1;
+				entry.bytes += Buffer.byteLength(text);
+				this.stats.windowsJudged++;
+			});
+		});
+
+		const hits: FindHit[] = [];
+		for (const [f, entry] of results) {
+			const plan = files[f]!;
+			this.stats.filesRead++;
+			this.stats.fileBytes += entry.bytes;
+			if (entry.score < THRESHOLD) continue;
+			hits.push({
+				rel: entries[plan.node]!.rel,
+				nameScore: nameScore[plan.node],
+				contentScore: entry.score,
+				ranges: mergeHeat(entry.heat, THRESHOLD),
+				linesSeen: entry.lines,
+				truncated: plan.truncated || entry.lines < plan.total,
+			});
+		}
+		this.stats.fileBytes += sketchSentBytes;
+		this.stats.filesRead += files.length - results.size;
+		hits.sort((a, b) => b.contentScore - a.contentScore);
+		return { hits, threshold: THRESHOLD, keywords, stats: this.stats };
+	}
+}
+
+/** Run one cascade search over `options.root`. Judge failures degrade coverage and are reported in `stats.failures`, never thrown. */
+export function runCascade(options: CascadeOptions): Promise<CascadeResult> {
+	return new Cascade(options).run();
+}

package/src/cascade/keywords.ts

@@ -0,0 +1,181 @@
+/**
+ * Query-derived keywords for the lexical prior: quoted phrases whole, then
+ * alphanumeric tokens minus stopwords, cheaply stemmed and deduplicated.
+ *
+ * Ported verbatim from oh-my-pi `packages/coding-agent/src/tools/jfind/keywords.ts` (MIT).
+ */
+
+const STOPWORDS: Record<string, true> = Object.fromEntries(
+	[
+		"the",
+		"a",
+		"an",
+		"or",
+		"and",
+		"to",
+		"is",
+		"are",
+		"be",
+		"when",
+		"where",
+		"how",
+		"that",
+		"this",
+		"of",
+		"in",
+		"on",
+		"at",
+		"for",
+		"with",
+		"by",
+		"its",
+		"it",
+		"as",
+		"from",
+		"into",
+		"like",
+		"gets",
+		"get",
+		"up",
+		"which",
+		"what",
+		"does",
+		"do",
+		"code",
+		"file",
+		"files",
+		"over",
+		"all",
+		"user",
+		"using",
+		"then",
+		"than",
+		"there",
+		"their",
+		"they",
+		"them",
+		"you",
+		"your",
+		"we",
+		"our",
+		"has",
+		"have",
+		"had",
+		"was",
+		"were",
+		"been",
+		"being",
+		"will",
+		"would",
+		"should",
+		"can",
+		"could",
+		"not",
+		"but",
+		"if",
+		"so",
+		"such",
+		"via",
+		"per",
+		"any",
+		"some",
+		"each",
+		"every",
+		"also",
+		"just",
+		"only",
+		"more",
+		"most",
+		"other",
+		"out",
+		"off",
+		"about",
+		"after",
+		"before",
+		"between",
+		"through",
+		"during",
+		"without",
+		"within",
+		"one",
+		"two",
+		"new",
+		"used",
+		"use",
+		"make",
+		"makes",
+		"made",
+		"run",
+		"runs",
+		"way",
+		"thing",
+		"things",
+		"something",
+		"actually",
+		"really",
+		"still",
+		"yet",
+	].map(word => [word, true]),
+);
+
+/** Cheap stem so a substring match covers inflections: spawned→spawn, compacted→compact. */
+function stem(token: string): string {
+	for (const suffix of ["ing", "ed", "es", "s"]) {
+		if (token.endsWith(suffix)) {
+			const base = token.slice(0, -suffix.length);
+			if (base.length >= 4) return base;
+		}
+	}
+	return token;
+}
+
+/** Unicode letter, digit, or underscore — the token alphabet of the query. */
+const TOKEN_RE = /[^\p{L}\p{N}_]+/u;
+const DIGITS_RE = /^[0-9]+$/;
+
+/** Keywords for the grep prior: quoted phrases whole, then tokens minus stopwords. */
+export function keywordsFromQuery(query: string): string[] {
+	const out: string[] = [];
+	let rest = "";
+	const chars = Array.from(query);
+	for (let i = 0; i < chars.length; i++) {
+		const c = chars[i]!;
+		if (c !== '"' && c !== "'") {
+			rest += c;
+			continue;
+		}
+		let phrase = "";
+		let closed = false;
+		while (++i < chars.length) {
+			if (chars[i] === c) {
+				closed = true;
+				break;
+			}
+			phrase += chars[i];
+		}
+		phrase = phrase.trim().toLowerCase();
+		if (closed && Buffer.byteLength(phrase) >= 3) {
+			out.push(phrase);
+			rest += " ";
+			continue;
+		}
+		rest += `${phrase} `;
+	}
+	for (const token of rest.split(TOKEN_RE)) {
+		const lower = token.toLowerCase();
+		if (Buffer.byteLength(lower) < 3 || Object.hasOwn(STOPWORDS, lower) || DIGITS_RE.test(lower)) continue;
+		const stemmed = stem(lower);
+		if (!out.includes(stemmed)) out.push(stemmed);
+	}
+	return out;
+}
+
+/** {@link keywordsFromQuery} plus the caller's extra keywords, lowercased and deduplicated. */
+export function keywords(query: string, extra: readonly string[]): string[] {
+	const out = keywordsFromQuery(query);
+	for (const raw of extra) {
+		const keyword = raw.trim().toLowerCase();
+		if (keyword.length > 0 && !out.includes(keyword)) out.push(keyword);
+	}
+	return out;
+}