@t50-systems/pi-fff-plus

T50-friendly Pi extension for safer FFF-powered file and content search on Windows and multi-root workspaces.

Product vision

Give Pi agents fast local search with explicit roots, bounded output, predictable path constraints, and paths that downstream Pi tools can consume directly. See docs/PRODUCT.md for measurable targets.

Tools

• fffind — fuzzy path search.
• ffgrep — bounded content search with context and pagination.
• fff-multi-grep — intentionally disabled by default, matching upstream.

Quickstart

1. Install

pi install git:github.com/T50-Systems/pi-fff-plus

Remove or disable npm:@ff-labs/pi-fff to avoid duplicate fffind/ffgrep registrations, then restart Pi or run /reload.

2. Check roots and index health

/fff-health

Default roots include the current Pi cwd, C:/dev/pi, ~/.pi/agent, ~/.agents, and the Windows global npm root when available.

3. Find a path

fffind pattern:"*.ts" path:"src/**" limit:20

4. Search content

ffgrep pattern:"registerTool" path:"src/**" exclude:["node_modules","dist"] context:2 limit:20

Results outside the active cwd are absolute and use /, so Pi read can consume them directly.

Configuration

Additional roots can be configured for the Pi process:

PI_FFF_ROOTS="D:/code;C:/other/root" pi

Comma-separated values are also accepted. Roots are normalized, deduplicated, and authorization is applied before search or index creation. Existing paths are resolved canonically: a symlink or junction that leaves its configured root is denied. Finder creation also uses best-effort pre/post canonical-path and filesystem-identity checks; this narrows selected replacement races but does not eliminate TOCTOU windows or provide an OS sandbox. Do not add broad sensitive directories unless agents should be able to search them.

T50 changes vs upstream

• Accepts absolute path values only when they are inside a configured root.
• Supports multiple configured roots across Windows and POSIX environments.
• Normalizes output paths to /.
• Emits absolute paths for results outside the active cwd.
• Treats ffgrep.limit as a global display cap, not a per-file cap.
• Enforces ffgrep limits of 1–50 matches and 0–5 context lines, fffind limits of 1–200 paths, and a 600-line/256 KiB formatted-output ceiling.
• Binds pagination cursors to the exact pattern, path, exclusions, case/context/limit options, mode, authorized root, and root generation.
• Invalidates continuation semantics after root refresh, rescan, mode change, finder destruction, or cursor eviction; retry without the cursor.
• Destroys and invalidates a newly created finder when pre/post root identity snapshots differ or post-create identity verification fails; this is explicitly best-effort, not race elimination.
• Explains configured roots and recovery steps in errors and /fff-health.

Commands

• /fff-health — show mode, active cwd, configured roots, and initialized index sizes.
• /fff-rescan — rescan initialized roots after large filesystem changes.
• /fff-mode <tools-and-ui|tools-only|override> — select tool registration behavior.

Troubleshooting

fffind or ffgrep is missing

Run pi list, remove duplicate upstream registrations, and restart Pi or run /reload after installation.

An absolute path is rejected

Run /fff-health. The selected path must be inside a configured root. Add the smallest necessary root through PI_FFF_ROOTS and restart Pi.

Recent files are missing

Run /fff-rescan, then retry with a bare identifier and a broader path constraint.

Output is truncated or a cursor is rejected

This is intentional. Continue using the returned cursor with every original query parameter unchanged, or narrow the path/pattern. Unknown, evicted, mismatched, or stale cursors fail closed; restart the same query without cursor. Caller limits outside the documented ranges are rejected rather than silently expanded.

Development

npm ci
npm run verify
npm run test:coverage
npm run benchmark
npm audit --audit-level=high
npm run verify:package

CI supports Node 22 on Ubuntu and Windows, plus Node 24 compatibility on Ubuntu. Platform-specific symlink/junction fixtures use capability detection without skipping unrelated assertions.

Load the checkout directly:

pi --no-extensions -e ./src/index.ts

Documentation

• docs/ARCHITECTURE.md — components, boundaries, flow, and extension points.
• docs/COMPATIBILITY.md — tested upstream APIs, semver range, update review, and rollback.
• SECURITY.md — supported versions and private disclosure routes.
• docs/GITHUB_ACTIONS.md — reviewed action pins, offline enforcement, Dependabot updates, permissions, and rollback.
• docs/THREAT_MODEL.md — root authorization, local data, database, dependency, and process boundaries.
• ROADMAP.md — issue-backed Next/Later/Deferred commitments, cadence, and ownership.
• docs/EXAMPLES.md — practical search and recovery recipes.
• docs/PERFORMANCE.md — reproducible local performance baseline.
• docs/PRODUCT.md — vision, promise, and success metrics.
• CONTRIBUTING.md — contributor setup and validation rules.
• CHANGELOG.md — release history.

Release workflow

Update package.json and CHANGELOG.md, merge validated changes, then create a matching vX.Y.Z tag. The release workflow verifies the reviewed upstream range and lockfile, typechecking, tests, dependency audit, package contents, and tag/version consistency. Evaluate and roll back upstream changes using docs/COMPATIBILITY.md; never rewrite a release tag. GitHub Releases are the distribution baseline; publishing to npm requires a separate explicit decision.

License

MIT