@heyhuynhgiabuu/pi-pretty 0.3.3 → 0.4.1

package/README.md

@@ -3,13 +3,14 @@
 [![npm version](https://img.shields.io/npm/v/@heyhuynhgiabuu/pi-pretty)](https://www.npmjs.com/package/@heyhuynhgiabuu/pi-pretty)
 [![GitHub release](https://img.shields.io/github/v/release/buddingnewinsights/pi-pretty)](https://github.com/buddingnewinsights/pi-pretty/releases/latest)
 
-A [pi](https://pi.dev) extension that upgrades built-in tool output in the terminal without changing tool behavior.
+A [pi](https://pi.dev) extension that upgrades built-in tool output in the terminal and includes built-in FFF-powered search for `find`/`grep`.
 
 It currently enhances:
 
 - **`read`**: syntax-highlighted text previews with line numbers, plus inline image rendering when the terminal supports it
 - **`bash`**: colored exit summary (`exit 0`/`exit 1`) with a preview body of command output
-- **`ls` / `find` / `grep`**: Nerd Font file icons with tree/grouped layouts and clearer match rendering
+- **`ls`**: Nerd Font file icons with tree-oriented rendering
+- **`find` / `grep`**: built-in FFF-backed search with frecency-aware results, plus grouped/highlighted rendering
 
 > Companion to [@heyhuynhgiabuu/pi-diff](https://github.com/buddingnewinsights/pi-diff) for `write`/`edit` diff rendering.
 
@@ -51,9 +52,13 @@ When running in **tmux**, pi-pretty uses passthrough escape sequences.
 >
 > (or run once in a session: `tmux set -g allow-passthrough on`)
 
-## FFF data directory
+## Bundled FFF search
 
-When FFF is available, pi-pretty now stores its frecency/history data under a pi-pretty-specific path:
+`pi-pretty` now bundles `@ff-labs/fff-node` and owns the built-in `find` / `grep` search behavior directly.
+
+If you use bundled FFF mode, do not load `pi-fff` at the same time, because Pi extensions do not compositionally share ownership of the same built-in tool names.
+
+FFF data is stored under a pi-pretty-specific path:
 
 ```text
 ~/.pi/agent/pi-pretty/fff/
@@ -61,6 +66,71 @@ When FFF is available, pi-pretty now stores its frecency/history data under a pi
 
 This makes it clear that the cache belongs to this extension rather than Pi core.
 
+## How to use it
+
+### 1. Install and load only `pi-pretty`
+
+```bash
+pi install npm:@heyhuynhgiabuu/pi-pretty
+```
+
+Do **not** also load `pi-fff` in the same Pi setup.
+
+### 2. Start Pi in a project
+
+```bash
+cd /path/to/your/project
+pi
+```
+
+On session start, pi-pretty initializes the bundled FFF index for the current working directory.
+
+### 3. Use the built-in tools normally
+
+You keep using the normal built-in tool names — pi-pretty owns them directly.
+
+Examples:
+
+```text
+find pattern="*.ts" path="src"
+grep pattern="handleRequest" glob="*.ts"
+read path="src/index.ts"
+ls path="src"
+```
+
+### 4. Use `multi_grep` when you want OR-search across multiple strings
+
+`multi_grep` is bundled on top of FFF and is useful when you want any of several patterns:
+
+```text
+multi_grep patterns=["handleRequest","handle_request","HandleRequest"] constraints="*.ts"
+```
+
+Good uses:
+- find several naming variants at once
+- search related symbols in one pass
+- replace slow regex alternation with literal OR matching
+
+### 5. Check FFF status or force a rescan
+
+pi-pretty also provides two maintenance commands:
+
+```text
+/fff-health
+/fff-rescan
+```
+
+Use them when:
+- you want to confirm indexing is active
+- the session started with a partial index warning
+- you made large filesystem changes and want a fresh scan
+
+### Notes
+
+- `find` results are frecency-aware, so files you touch more often can bubble up earlier.
+- `grep` and `multi_grep` can show a cursor notice when more results are available.
+- If you see a partial index warning, let the session settle or run `/fff-rescan`.
+
 ## Configuration
 
 Optional environment variables:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.3.3",
+	"version": "0.4.1",
 	"description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
 	"author": "huynhgiabuu",
 	"license": "MIT",
@@ -22,11 +22,9 @@
 		"pretty-print"
 	],
 	"dependencies": {
+		"@ff-labs/fff-node": "0.5.2",
 		"@shikijs/cli": "^4.0.2"
 	},
-	"optionalDependencies": {
-		"@ff-labs/fff-node": "0.5.2"
-	},
 	"peerDependencies": {
 		"@mariozechner/pi-coding-agent": "*",
 		"@mariozechner/pi-tui": "*"

package/release-notes/v0.4.0.md

@@ -0,0 +1,58 @@
+# pi-pretty v0.4.0
+
+## Summary
+This release makes bundled FFF search the primary product direction for `pi-pretty`.
+
+`pi-pretty` now owns the built-in `find` / `grep` experience directly via `@ff-labs/fff-node`, includes `multi_grep`, and documents the bundled workflow end-to-end.
+
+## What changed
+- Bundled `@ff-labs/fff-node` as a normal dependency instead of an optional coexistence path.
+- Restored bundled FFF-backed behavior for:
+  - `find`
+  - `grep`
+  - `multi_grep`
+  - `/fff-health`
+  - `/fff-rescan`
+- Kept the pi-pretty-specific FFF data directory:
+  - `~/.pi/agent/pi-pretty/fff/`
+- Updated README to document:
+  - bundled FFF ownership
+  - install/use flow
+  - `multi_grep` examples
+  - FFF maintenance commands
+  - the requirement not to co-load `pi-fff`
+- Tightened FFF/runtime typing:
+  - typed `CursorStore` and `fffFormatGrepText()` against `@ff-labs/fff-node`
+  - replaced remaining `src/index.ts` explicit `any` usage in tool wrappers with SDK/FFF-backed types
+  - typed `find`, `grep`, and `multi_grep` params/results/render paths against Pi tool inputs and FFF result interfaces
+  - removed several dead imports/constants and a non-null assertion in renderer code
+
+## Files
+- `src/index.ts`
+- `src/fff-helpers.ts`
+- `test/fff-integration.test.ts`
+- `test/image-rendering.test.ts`
+- `README.md`
+- `package.json`
+- `package-lock.json`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm test` ✅ (47 tests)
+- `npm run lint -- --max-diagnostics=120` ✅
+- `rg "\\bany\\b" src/index.ts src/fff-helpers.ts` ✅ no matches
+
+## Upgrade notes
+- Use only `pi-pretty` for bundled FFF mode:
+
+```bash
+pi install npm:@heyhuynhgiabuu/pi-pretty
+```
+
+- Do **not** also load `pi-fff` in the same Pi setup.
+- To inspect or refresh the bundled index inside Pi, use:
+
+```text
+/fff-health
+/fff-rescan
+```

package/release-notes/v0.4.1.md

@@ -0,0 +1,28 @@
+# pi-pretty v0.4.1
+
+## Summary
+This patch release prevents `grep` from aborting Pi when FFF 0.5.2 indexes Unicode filenames and the grep call includes a `path` or `glob` constraint.
+
+## What changed
+- Constrained `grep` calls now bypass native FFF and use the SDK fallback path.
+- Unconstrained `grep` still uses FFF for the fast path.
+- Added regression tests for both `path` and `glob` constrained grep bypass behavior.
+
+## Why
+`@ff-labs/fff-node@0.5.2` can panic inside native Rust constraint matching when a byte-based slice lands inside a multi-byte UTF-8 character in an indexed filename, such as an en dash (`–`). Because that panic happens across FFI, JavaScript cannot catch it; the whole `pi` process aborts.
+
+This release avoids the crash-prone native constraint path until upstream FFF ships the Unicode boundary fix.
+
+## Files
+- `src/index.ts`
+- `test/fff-integration.test.ts`
+- `package.json`
+- `package-lock.json`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm run lint` ✅
+- `npm test` ✅ (48 tests)
+
+## Upgrade notes
+No configuration changes required. After updating, file- or glob-scoped `grep` calls will prefer the SDK fallback for stability; broad unconstrained grep remains FFF-backed.

package/src/fff-helpers.ts

@@ -4,12 +4,14 @@
  * Pure functions and classes used by the FFF integration in index.ts.
  */
 
+import type { GrepCursor, GrepMatch } from "@ff-labs/fff-node";
+
 /**
  * Store for FFF grep pagination cursors.
  * Evicts oldest entry when exceeding maxSize.
  */
 export class CursorStore {
-	private cursors = new Map<string, any>();
+	private cursors = new Map<string, GrepCursor>();
 	private counter = 0;
 	private maxSize: number;
 
@@ -17,7 +19,7 @@ export class CursorStore {
 		this.maxSize = maxSize;
 	}
 
-	store(cursor: any): string {
+	store(cursor: GrepCursor): string {
 		const id = `fff_c${++this.counter}`;
 		this.cursors.set(id, cursor);
 		if (this.cursors.size > this.maxSize) {
@@ -27,7 +29,7 @@ export class CursorStore {
 		return id;
 	}
 
-	get(id: string): any | undefined {
+	get(id: string): GrepCursor | undefined {
 		return this.cursors.get(id);
 	}
 
@@ -40,7 +42,7 @@ export class CursorStore {
  * Convert FFF GrepResult items to ripgrep-style "file:line:content" text.
  * This ensures pi-pretty's renderGrepResults works unchanged.
  */
-export function fffFormatGrepText(items: any[], limit: number): string {
+export function fffFormatGrepText(items: GrepMatch[], limit: number): string {
 	const capped = items.slice(0, limit);
 	if (!capped.length) return "No matches found";
 
@@ -58,8 +60,7 @@ export function fffFormatGrepText(items: any[], limit: number): string {
 				lines.push(`${match.relativePath}-${startLine + i}-${match.contextBefore[i]}`);
 			}
 		}
-		const content =
-			match.lineContent.length > 500 ? `${match.lineContent.slice(0, 500)}...` : match.lineContent;
+		const content = match.lineContent.length > 500 ? `${match.lineContent.slice(0, 500)}...` : match.lineContent;
 		lines.push(`${match.relativePath}:${match.lineNumber}:${content}`);
 		if (match.contextAfter?.length) {
 			const startLine = match.lineNumber + 1;