Skip to content

Find code by asking what it does. A CLI for coding agents that uses Jev to discover relevant files and source context.

feat(cli): show terminal search progress

David Zhang2e4be714bb1e
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index e6cb438..314504f 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -1,6 +1,7 @@
#!/usr/bin/env node
import { authenticate, loadCredentials } from "./auth";
import { endpointFor } from "@repo/core/providers";
+import type { Inventory, RetrievalResult } from "@repo/core";
import { storageDirectory } from "@repo/core/storage";
import { help, parseCommand } from "./args";
import { CliError } from "./errors";
@@ -8,6 +9,7 @@ import { renderInventory, renderResult } from "./render";
import { stat } from "node:fs/promises";
import { version } from "../package.json";
import { installSkill } from "./skill";
+import { createProgress } from "./progress";
globalThis.AI_SDK_LOG_WARNINGS = false;
@@ -32,6 +34,13 @@ async function write(text: string) {
});
}
+function terminalProgress() {
+ return createProgress({
+ enabled: process.stdout.isTTY === true && process.stderr.isTTY === true && !process.env.CI,
+ write: (text) => process.stderr.write(text),
+ });
+}
+
async function main() {
const command = parseCommand(process.argv.slice(2));
switch (command.kind) {
@@ -96,12 +105,20 @@ async function main() {
if (!(await stat(command.root).catch(() => undefined))?.isDirectory())
throw new CliError("The root must be an existing directory.");
const { inventory } = await import("@repo/core");
- const result = await inventory({
- root: command.root,
- includePaths: command.list,
- policy: command.policy,
- signal: controller.signal,
- });
+ const progress = terminalProgress();
+ progress.start();
+ let result: Inventory;
+ try {
+ result = await inventory({
+ root: command.root,
+ includePaths: command.list,
+ policy: command.policy,
+ signal: controller.signal,
+ progress: (snapshot) => progress.update(snapshot),
+ });
+ } finally {
+ progress.done();
+ }
if (pipeClosed) return;
await write(renderInventory(result));
process.exitCode =
@@ -123,15 +140,23 @@ async function main() {
...credentials,
signal: controller.signal,
});
- const result = await retrieve(
- {
- root: command.root,
- query: command.query,
- policy: command.policy,
- signal: controller.signal,
- },
- evaluator,
- );
+ const progress = terminalProgress();
+ progress.start();
+ let result: RetrievalResult;
+ try {
+ result = await retrieve(
+ {
+ root: command.root,
+ query: command.query,
+ policy: command.policy,
+ signal: controller.signal,
+ progress: (snapshot) => progress.update(snapshot),
+ },
+ evaluator,
+ );
+ } finally {
+ progress.done();
+ }
if (pipeClosed) return;
await write(
renderResult(result, command.maxSourceBytes, command.maxOutputBytes, command.noLocations),
diff --git a/apps/cli/src/progress.ts b/apps/cli/src/progress.ts
new file mode 100644
index 0000000..d6e8ee7
--- /dev/null
+++ b/apps/cli/src/progress.ts
@@ -0,0 +1,63 @@
+import type { ProgressSnapshot } from "@repo/core";
+
+type ProgressOptions = {
+ enabled: boolean;
+ write: (text: string) => void;
+};
+
+const frames = ["-", "\\", "|", "/"];
+
+function size(bytes: number): string {
+ if (bytes < 1024) return `${bytes} B`;
+ const units = ["KiB", "MiB", "GiB"];
+ let value = bytes / 1024;
+ let unit = 0;
+ while (unit < units.length - 1 && value >= 1024) {
+ value /= 1024;
+ unit++;
+ }
+ return `${value.toFixed(1)} ${units[unit]}`;
+}
+
+export function createProgress(options: ProgressOptions) {
+ let active = false;
+ let frame = 0;
+ let snapshot: ProgressSnapshot = { files: 0, bytes: 0 };
+ let timer: ReturnType<typeof setInterval> | undefined;
+ let lastRenderedAt = 0;
+
+ const render = (force = false) => {
+ if (!active) return;
+ const now = Date.now();
+ if (!force && now - lastRenderedAt < 100) return;
+ lastRenderedAt = now;
+ options.write(
+ `\r\u001b[2K${frames[frame]} Searching — ${snapshot.files} ${snapshot.files === 1 ? "file" : "files"} · ${size(snapshot.bytes)}`,
+ );
+ };
+
+ return {
+ start() {
+ if (!options.enabled || active) return;
+ active = true;
+ render(true);
+ timer = setInterval(() => {
+ frame = (frame + 1) % frames.length;
+ render(true);
+ }, 120);
+ timer.unref?.();
+ },
+ update(next: ProgressSnapshot) {
+ if (!options.enabled) return;
+ snapshot = next;
+ render();
+ },
+ done() {
+ if (!active) return;
+ active = false;
+ if (timer) clearInterval(timer);
+ timer = undefined;
+ options.write("\r\u001b[2K");
+ },
+ };
+}
diff --git a/apps/cli/test/progress.test.ts b/apps/cli/test/progress.test.ts
new file mode 100644
index 0000000..8da2275
--- /dev/null
+++ b/apps/cli/test/progress.test.ts
@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+import { createProgress } from "../src/progress";
+
+test("disabled progress emits no terminal bytes", () => {
+ const output: string[] = [];
+ const progress = createProgress({ enabled: false, write: (text) => output.push(text) });
+
+ progress.start();
+ progress.update({ files: 3, bytes: 2048 });
+ progress.done();
+
+ expect(output).toEqual([]);
+});
+
+test("interactive progress keeps one live row with file and byte counts", async () => {
+ const output: string[] = [];
+ const progress = createProgress({ enabled: true, write: (text) => output.push(text) });
+
+ progress.start();
+ await new Promise((resolve) => setTimeout(resolve, 110));
+ progress.update({ files: 3, bytes: 2048 });
+ progress.done();
+
+ expect(output.join("")).toContain("Searching — 3 files · 2.0 KiB");
+ expect(output.at(-1)).toBe("\r\u001b[2K");
+});
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index bb71499..379f7f1 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -3,4 +3,4 @@ export { createEvaluator, EvaluationFailure } from "./evaluator";
export { createEvaluationCache } from "./cache";
export { inventory } from "./inventory";
export type { Inventory } from "./inventory";
-export type { SearchInput, RetrievalResult, FileEvidence } from "./types";
+export type { SearchInput, RetrievalResult, FileEvidence, ProgressSnapshot } from "./types";
diff --git a/packages/core/src/inventory.ts b/packages/core/src/inventory.ts
index 3cad143..764f222 100644
--- a/packages/core/src/inventory.ts
+++ b/packages/core/src/inventory.ts
@@ -1,4 +1,5 @@
import { createFilesystem, type FilesystemPolicy } from "./filesystem";
+import type { ProgressSnapshot } from "./types";
export type InventoryInput = {
root: string;
@@ -9,6 +10,7 @@ export type InventoryInput = {
includePaths?: boolean;
/** Matches the entry bound search discovery applies in retrieve.ts. */
maxEntries?: number;
+ progress?: (snapshot: ProgressSnapshot) => void;
};
export type Inventory = {
status: "complete" | "incomplete" | "interrupted";
@@ -39,6 +41,13 @@ export async function inventory(input: InventoryInput): Promise<Inventory> {
let seen = 0;
const paths = input.includePaths ? ([] as string[]) : undefined;
const pending = ["."];
+ const reportProgress = () => {
+ try {
+ input.progress?.({ files, bytes });
+ } catch {
+ // Progress is observational and must never change inventory behavior.
+ }
+ };
try {
walk: for (let next = 0; next < pending.length; next++) {
let cursor: string | undefined;
@@ -68,6 +77,7 @@ export async function inventory(input: InventoryInput): Promise<Inventory> {
files++;
bytes += entry.bytes ?? 0;
paths?.push(entry.path);
+ reportProgress();
}
} while (cursor);
} finally {
diff --git a/packages/core/src/retrieve.ts b/packages/core/src/retrieve.ts
index e13b30d..71e365f 100644
--- a/packages/core/src/retrieve.ts
+++ b/packages/core/src/retrieve.ts
@@ -92,12 +92,22 @@ export async function retrieve(input: SearchInput, evaluator: Evaluator): Promis
let confidentSourceSeen = false;
const sourceProbes = new Set<string>();
const firstSelections = new Map<string, { contentHash: string; selection: SelectionResult }>();
+ let progressBytes = 0;
let stop = false;
function issue(kind: string, count = 1, message?: string) {
if (kind === "provider") providerFailure ??= message;
issues.set(kind, (issues.get(kind) ?? 0) + count);
if (["authentication", "request-limit", "cancelled", "interrupted"].includes(kind)) stop = true;
}
+ function reportSnapshot(snapshot: Snapshot) {
+ if (!inspected.add(snapshot.path)) return;
+ progressBytes += Buffer.byteLength(snapshot.source);
+ try {
+ input.progress?.({ files: inspected.size, bytes: progressBytes });
+ } catch {
+ // Progress is observational and must never change search behavior.
+ }
+ }
async function snapshot(path: string) {
const result = await reader.readSnapshot(path, { reuse: true });
if (result.status === "issue") {
@@ -105,7 +115,7 @@ export async function retrieve(input: SearchInput, evaluator: Evaluator): Promis
return;
}
if (result.status === "excluded") return;
- inspected.add(path);
+ reportSnapshot(result.snapshot);
return result.snapshot;
}
function isCancellation(error: unknown) {
@@ -594,7 +604,7 @@ export async function retrieve(input: SearchInput, evaluator: Evaluator): Promis
// Unchanged file identity reuses the reader's earlier snapshot; any change rereads and rehashes.
const result = await reader.readSnapshot(candidate.path, { reuse: true });
if (result.status === "ok" && result.snapshot.contentHash === candidate.contentHash) {
- inspected.add(candidate.path);
+ reportSnapshot(result.snapshot);
return result.snapshot;
}
issue(result.status === "issue" ? result.issue.kind : "changed");
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 3cd2cbb..a32abf4 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -46,12 +46,14 @@ export type RetrievalResult = {
};
counts: { requests: number; cacheHits: number; inspectedFiles: number };
};
+export type ProgressSnapshot = { files: number; bytes: number };
export type SearchInput = {
root: string;
query: string;
policy?: FilesystemPolicy;
signal: AbortSignal;
protectedPaths?: string[];
+ progress?: (snapshot: ProgressSnapshot) => void;
};
export type Evaluator = {
readonly requests: number;
diff --git a/packages/core/test/inventory-list.test.ts b/packages/core/test/inventory-list.test.ts
index a012c93..ae0be8d 100644
--- a/packages/core/test/inventory-list.test.ts
+++ b/packages/core/test/inventory-list.test.ts
@@ -62,3 +62,23 @@ test("inventory optionally retains eligible paths and respects exclusions and en
await rm(root, { recursive: true, force: true });
}
});
+
+test("inventory progress reports cumulative eligible files and bytes", async () => {
+ const root = await mkdtemp(join(tmpdir(), "jevgrep-inventory-progress-"));
+ try {
+ await writeFile(join(root, "a.ts"), "a");
+ await writeFile(join(root, "b.ts"), "bb");
+ const updates: Array<{ files: number; bytes: number }> = [];
+
+ const result = await inventory({
+ root,
+ signal: new AbortController().signal,
+ progress: (snapshot) => updates.push(snapshot),
+ });
+
+ expect(result.files).toBe(2);
+ expect(updates.at(-1)).toEqual({ files: 2, bytes: 3 });
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});