@ff-labs/pi-fff 0.10.6-nightly.e6df253 → 0.10.6

package/README.md

@@ -143,7 +143,9 @@ For persistent global configuration, create `pi-fff.json` in pi's agent director
   "frecencyDbPath": "/path/to/frecency",
   "historyDbPath": "/path/to/history",
   "enableFsRootScanning": false,
-  "enableHomeDirScanning": true
+  "enableHomeDirScanning": true,
+  "warnOnHomeDirScan": true,
+  "followSymlinks": true
 }
 ```
 
@@ -157,6 +159,8 @@ All fields are optional:
 | `historyDbPath` | non-empty string | See [Data](#data) |
 | `enableFsRootScanning` | boolean | `false` |
 | `enableHomeDirScanning` | boolean | `true` |
+| `warnOnHomeDirScan` | boolean | `true` |
+| `followSymlinks` | boolean | `true` |
 
 CLI flags take precedence over environment variables, which take precedence over this file. A missing file is ignored. Malformed JSON, unknown fields, and invalid values stop the extension from loading and report the file path and error. `/fff-mode` changes the current session; it does not edit this file.
 
@@ -169,6 +173,8 @@ The file is global only. Project-level config cannot safely control tool names b
 - `--fff-history-db <path>` — path to query history database (also: `FFF_HISTORY_DB` env). Optional; see [Data](#data) for the default.
 - `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default.
 - `--fff-enable-home-scan` — index the home directory when launched from `$HOME` (also: `FFF_ENABLE_HOME_SCAN` env). Enabled by default. Disable with `--fff-enable-home-scan=false` or `FFF_ENABLE_HOME_SCAN=0` if your `$HOME` contains huge trees (toolchains, kernel sources, build outputs) that make the background index run for a long time. When launched from `$HOME` with this enabled, pi shows a warning that the whole home tree is being indexed.
+- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Disable with `--fff-warn-home-scan=false`, `FFF_WARN_HOME_SCAN=0`, or `"warnOnHomeDirScan": false` in `pi-fff.json`. Indexing and the footer status are unaffected.
+- `--fff-follow-symlinks` — index through directory symlinks (also: `FFF_FOLLOW_SYMLINKS` env, or `"followSymlinks"` in `pi-fff.json`). Enabled by default: trees that reach their real files through links — a git worktree whose `docs/` links back to the main checkout, or a stowed dotfiles layout — would otherwise be missing from `@`-mentions and from find/grep with no visible sign. Disable with `--fff-follow-symlinks=false` or `FFF_FOLLOW_SYMLINKS=0` to keep the walk inside the real tree, which is worth doing when a linked target pulls in a large tree outside the workspace. Symlink cycles are detected and broken by the walker.
 
 ## Data
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ff-labs/pi-fff",
   "public": true,
-  "version": "0.10.6-nightly.e6df253",
+  "version": "0.10.6",
   "description": "pi extension: FFF-powered fuzzy file and content search",
   "type": "module",
   "license": "MIT",
@@ -41,8 +41,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ff-labs/fff-bun": "0.10.6-nightly.e6df253",
-    "@ff-labs/fff-node": "0.10.6-nightly.e6df253"
+    "@ff-labs/fff-bun": "0.10.6",
+    "@ff-labs/fff-node": "0.10.6"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/pi-fff.schema.json

@@ -36,6 +36,16 @@
       "type": "boolean",
       "default": true,
       "description": "Allows indexing when pi is launched from the home directory."
+    },
+    "warnOnHomeDirScan": {
+      "type": "boolean",
+      "default": true,
+      "description": "Shows a warning notification when the home directory is indexed."
+    },
+    "followSymlinks": {
+      "type": "boolean",
+      "default": true,
+      "description": "Indexes through directory symlinks, e.g. a git worktree or stow layout whose files live behind links. Set to false to keep the walk inside the real tree."
     }
   }
 }

package/src/aux-finders.ts

@@ -16,6 +16,7 @@ interface AuxPicker {
 export interface AuxOpts {
   enableFsRootScanning: boolean;
   enableHomeDirScanning?: boolean;
+  followSymlinks?: boolean;
   pickers: FilePickerFactory;
   // Called before a newly spawned aux picker starts a scan that covers $HOME.
   onHomeDirScan?: (root: string) => void;
@@ -104,6 +105,7 @@ export class AuxFinderPool {
       basePath: root,
       enableHomeDirScanning,
       enableFsRootScanning: this.opts.enableFsRootScanning,
+      followSymlinks: this.opts.followSymlinks,
     });
 
     const entry: AuxPicker = { root, finder, lastUsed: Date.now() };

package/src/config.ts

@@ -14,6 +14,8 @@ export interface FffConfig {
   historyDbPath?: string;
   enableFsRootScanning?: boolean;
   enableHomeDirScanning?: boolean;
+  warnOnHomeDirScan?: boolean;
+  followSymlinks?: boolean;
 }
 
 const CONFIG_KEYS = new Set<keyof FffConfig>([
@@ -23,6 +25,8 @@ const CONFIG_KEYS = new Set<keyof FffConfig>([
   "historyDbPath",
   "enableFsRootScanning",
   "enableHomeDirScanning",
+  "warnOnHomeDirScan",
+  "followSymlinks",
 ]);
 
 export function loadConfig(agentDir = piDataDir()): FffConfig {
@@ -64,6 +68,8 @@ export function loadConfig(agentDir = piDataDir()): FffConfig {
   validateString(configPath, parsed, "historyDbPath");
   validateBoolean(configPath, parsed, "enableFsRootScanning");
   validateBoolean(configPath, parsed, "enableHomeDirScanning");
+  validateBoolean(configPath, parsed, "warnOnHomeDirScan");
+  validateBoolean(configPath, parsed, "followSymlinks");
 
   return parsed as FffConfig;
 }
@@ -94,7 +100,11 @@ function validateString(
 function validateBoolean(
   configPath: string,
   config: Record<string, unknown>,
-  key: "enableFsRootScanning" | "enableHomeDirScanning",
+  key:
+    | "enableFsRootScanning"
+    | "enableHomeDirScanning"
+    | "warnOnHomeDirScan"
+    | "followSymlinks",
 ): void {
   const value = config[key];
   if (value !== undefined && typeof value !== "boolean") {

package/src/file-picker.ts

@@ -5,6 +5,7 @@ export interface PickerOptions {
   basePath: string;
   enableHomeDirScanning?: boolean;
   enableFsRootScanning?: boolean;
+  followSymlinks?: boolean;
 }
 
 /** Opens every picker in this pi process — the cwd picker and the aux pickers —

package/src/index.ts

@@ -40,6 +40,10 @@ export { SCAN_TIMEOUT_MS } from "./sdk";
 const DEFAULT_GREP_LIMIT = 20;
 const DEFAULT_FIND_LIMIT = 30;
 const GREP_PAGE_SIZE_MAX = 50;
+// Per-file match cap. Must stay decoupled from pageSize: grep cursors advance by
+// file offset, so clamping this to pageSize makes same-file overflow unreachable
+// on later pages (#825). Matches the engine default.
+const GREP_MAX_MATCHES_PER_FILE = 200;
 const GREP_CONTEXT_MAX = 20;
 const GREP_MAX_LINE_LENGTH = 500;
 const MENTION_MAX_RESULTS = 20;
@@ -50,7 +54,8 @@ const GREP_TIME_BUDGET_MS = 10_000;
 const HOME_SCAN_STATUS_KEY = "fff";
 const HOME_SCAN_POLL_MS = 1_000;
 const HOME_SCAN_DISABLE_HINT =
-  "You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or enableHomeDirScanning in pi-fff.json.";
+  'You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or "enableHomeDirScanning": false in pi-fff.json. ' +
+  'To keep indexing but silence this warning use --fff-warn-home-scan=false, FFF_WARN_HOME_SCAN=0, or "warnOnHomeDirScan": false in pi-fff.json.';
 
 interface ToolNames {
   grep: string;
@@ -343,6 +348,8 @@ export default function fffExtension(pi: ExtensionAPI) {
   let resolvedDbPaths: ReturnType<typeof resolveDbPaths>;
   let enableFsRootScanning = false;
   let enableHomeDirScanning = true;
+  let warnOnHomeDirScan = true;
+  let followSymlinks = true;
 
   function setMode(mode: FffMode): void {
     currentMode = mode;
@@ -385,6 +392,22 @@ export default function fffExtension(pi: ExtensionAPI) {
       true,
       parseBoolean,
     );
+    warnOnHomeDirScan = getConfigValue(
+      "fff-warn-home-scan",
+      "FFF_WARN_HOME_SCAN",
+      config.warnOnHomeDirScan,
+      true,
+      parseBoolean,
+    );
+    // On by default: worktree and stow layouts reach their files through links,
+    // and an agent silently missing them is worse than the extra walk.
+    followSymlinks = getConfigValue(
+      "fff-follow-symlinks",
+      "FFF_FOLLOW_SYMLINKS",
+      config.followSymlinks,
+      true,
+      parseBoolean,
+    );
   }
 
   function getMode(): FffMode {
@@ -406,6 +429,7 @@ export default function fffExtension(pi: ExtensionAPI) {
   let homeScanTimer: ReturnType<typeof setInterval> | null = null;
 
   function warnHomeDirScan(root: string): void {
+    if (!warnOnHomeDirScan) return;
     uiCtx?.ui.notify(
       `(fff): Your cwd (${root}) is too large. Indexing will take additional time and resources.\n${HOME_SCAN_DISABLE_HINT}`,
       "warning",
@@ -430,6 +454,7 @@ export default function fffExtension(pi: ExtensionAPI) {
     auxPool = new AuxFinderPool({
       enableFsRootScanning,
       enableHomeDirScanning,
+      followSymlinks,
       onHomeDirScan: warnHomeDirScan,
       pickers,
     });
@@ -456,6 +481,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         basePath: cwd,
         enableHomeDirScanning,
         enableFsRootScanning,
+        followSymlinks,
       });
       finderCwd = cwd;
       return mainFinder;
@@ -667,6 +693,18 @@ export default function fffExtension(pi: ExtensionAPI) {
     type: "boolean",
   });
 
+  pi.registerFlag("fff-follow-symlinks", {
+    description:
+      "Index through directory symlinks, e.g. a git worktree or stow layout (default true; disable with --fff-follow-symlinks=false or FFF_FOLLOW_SYMLINKS=0)",
+    type: "boolean",
+  });
+
+  pi.registerFlag("fff-warn-home-scan", {
+    description:
+      "Warn when indexing $HOME (default true; silence with --fff-warn-home-scan=false or FFF_WARN_HOME_SCAN=0)",
+    type: "boolean",
+  });
+
   function reportInitFailure(ctx: ExtensionContext, error: unknown): void {
     ctx.ui.notify(
       `FFF init failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -833,8 +871,9 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       const picker = aux ? aux.finder : await ensureFinder(activeCwd);
       const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
-      // pageSize caps TOTAL matches across all files; maxMatchesPerFile alone
-      // only caps per-file, so limit=5 could still return a full SDK page.
+      // pageSize caps TOTAL matches across all files (soft cap: the current file
+      // is always finished first). maxMatchesPerFile stays decoupled at the engine
+      // default so same-file overflow remains reachable via cursor (#825).
       const pageSize = Math.min(effectiveLimit, GREP_PAGE_SIZE_MAX);
       const context = clampContext(params.context);
       const query = aux
@@ -884,7 +923,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       const grepResult = picker.grep(query, {
         mode,
         smartCase,
-        maxMatchesPerFile: pageSize,
+        maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
         pageSize,
         cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
         beforeContext: context,
@@ -917,7 +956,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         const fuzzy = picker.grep(fuzzyQuery, {
           mode: "fuzzy",
           smartCase,
-          maxMatchesPerFile: pageSize,
+          maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
           pageSize,
           cursor: null,
           beforeContext: 0,
@@ -1167,7 +1206,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         const grepResult = f.multiGrep({
           patterns: params.patterns,
           constraints: params.constraints,
-          maxMatchesPerFile: pageSize,
+          maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
           pageSize,
           smartCase: true,
           cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,