fix(pi-fff): allow muting the $HOME scan warning (#806)

packages/pi-fff/README.md

@@ -143,7 +143,8 @@ 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
 }
 ```
 
@@ -157,6 +158,7 @@ All fields are optional:
 | `historyDbPath` | non-empty string | See [Data](#data) |
 | `enableFsRootScanning` | boolean | `false` |
 | `enableHomeDirScanning` | boolean | `true` |
+| `warnOnHomeDirScan` | 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 +171,7 @@ 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.
 
 ## Data
 

packages/pi-fff/pi-fff.schema.json

@@ -36,6 +36,11 @@
       "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."
     }
   }
 }

packages/pi-fff/src/config.ts

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

packages/pi-fff/src/index.ts

@@ -50,7 +50,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 +344,7 @@ export default function fffExtension(pi: ExtensionAPI) {
   let resolvedDbPaths: ReturnType<typeof resolveDbPaths>;
   let enableFsRootScanning = false;
   let enableHomeDirScanning = true;
+  let warnOnHomeDirScan = true;
 
   function setMode(mode: FffMode): void {
     currentMode = mode;
@@ -385,6 +387,13 @@ export default function fffExtension(pi: ExtensionAPI) {
       true,
       parseBoolean,
     );
+    warnOnHomeDirScan = getConfigValue(
+      "fff-warn-home-scan",
+      "FFF_WARN_HOME_SCAN",
+      config.warnOnHomeDirScan,
+      true,
+      parseBoolean,
+    );
   }
 
   function getMode(): FffMode {
@@ -406,6 +415,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",
@@ -667,6 +677,12 @@ export default function fffExtension(pi: ExtensionAPI) {
     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)}`,

packages/pi-fff/test/config.test.ts

@@ -31,6 +31,7 @@ describe("loadConfig", () => {
       historyDbPath: "/data/history",
       enableFsRootScanning: true,
       enableHomeDirScanning: false,
+      warnOnHomeDirScan: false,
     };
     writeConfig(config);
 
@@ -66,6 +67,7 @@ describe("loadConfig", () => {
       [{ historyDbPath: false }, '"historyDbPath" must be a non-empty string'],
       [{ enableFsRootScanning: 1 }, '"enableFsRootScanning" must be a boolean'],
       [{ enableHomeDirScanning: "false" }, '"enableHomeDirScanning" must be a boolean'],
+      [{ warnOnHomeDirScan: "false" }, '"warnOnHomeDirScan" must be a boolean'],
     ];
 
     for (const [config, message] of cases) {

packages/pi-fff/test/extension.test.ts

@@ -190,6 +190,7 @@ const CONFIG_ENV_KEYS = [
   "FFF_HISTORY_DB",
   "FFF_ENABLE_ROOT_SCAN",
   "FFF_ENABLE_HOME_SCAN",
+  "FFF_WARN_HOME_SCAN",
 ] as const;
 
 const savedEnv: Record<string, string | undefined> = {};
@@ -425,6 +426,39 @@ describe("pi-fff $HOME scan warning", () => {
     expect(setup.ctx.ui.setStatus).not.toHaveBeenCalled();
     await shutdown(setup);
   });
+
+  // #806: muting the warning must not turn the scan or the footer off.
+  test("FFF_WARN_HOME_SCAN=0 mutes the warning but keeps indexing", async () => {
+    process.env.FFF_WARN_HOME_SCAN = "0";
+    const setup = await start(undefined, os.homedir());
+
+    expect(setup.ctx.ui.notify).not.toHaveBeenCalled();
+    expect(setup.ctx.ui.setStatus).toHaveBeenCalledWith(
+      "fff",
+      "Agent is indexing $HOME, this can lead to high CPU",
+    );
+    expect(
+      (createCalls[0] as { enableHomeDirScanning: boolean }).enableHomeDirScanning,
+    ).toBe(true);
+    await shutdown(setup);
+  });
+
+  test("--fff-warn-home-scan=false mutes the warning", async () => {
+    const setup = await start(undefined, os.homedir(), {
+      "fff-warn-home-scan": false,
+    });
+
+    expect(setup.ctx.ui.notify).not.toHaveBeenCalled();
+    await shutdown(setup);
+  });
+
+  test("warnOnHomeDirScan in the config file mutes the warning", async () => {
+    writeConfig({ warnOnHomeDirScan: false });
+    const setup = await start(undefined, os.homedir());
+
+    expect(setup.ctx.ui.notify).not.toHaveBeenCalled();
+    await shutdown(setup);
+  });
 });
 
 describe("pi-fff autocomplete registration", () => {