@nklisch/pi-enhanced 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @nklisch/pi-enhanced
+
+Pi, enhanced — nklisch's full harness in one install. Policy-gated command
+review, a plugin marketplace with Claude Code/Codex compatibility, ordered
+subagent lifecycles, background tasks, web/repo research, fast indexed
+search, model-aware prompting, and a curated daily-driver UX set.
+
+```sh
+pi install npm:@nklisch/pi-enhanced
+```
+
+That's the whole setup. Everything below arrives bundled in the tarball —
+no separate installs, no version hunting.
+
+## What's inside
+
+### First-party (`@nklisch/*`)
+
+| Package | What you get |
+| --- | --- |
+| pi-clearance | Structural command policy: deterministic allow/deny, one review path for uncertainty (`/clearance`). |
+| pi-plugins | Plugin marketplace and lifecycle management, adopting Claude Code and Codex plugins natively. |
+| pi-subagents | Subagents with ordered lifecycle interception (bundled inside pi-plugins). |
+| pi-background-tasks | Background jobs with polling, status, cancellation, and wakeups. |
+| pi-model-modes | System-prompt adaptation per model and mode. |
+| pi-conveniences | `/exit`, `.agents/AGENTS.md` context loading, context-window footer, subagent model listing. |
+| pi-fff-compat | FFF-indexed file search through Pi-native find/grep semantics (no fuzzy fallback). |
+
+(`@nklisch/pi-zai-research` remains published separately if you prefer its
+Z.ai-backed research tools over pi-web-access.)
+
+### Curated third-party
+
+| Package | What you get |
+| --- | --- |
+| pi-catppuccin-tui | Catppuccin theme + TUI polish. |
+| pi-tool-display | Richer tool-call rendering. |
+| @narumitw/pi-usage | Usage/cost tracking. |
+| @juicesharp/rpiv-todo | Todo tracking. |
+| @juicesharp/rpiv-ask-user-question | Structured agent questions. |
+| @ff-labs/pi-fff | Fuzzy file discovery (ffind/ffgrep) — complements pi-fff-compat. |
+| pi-web-access | Web search and page fetching. |
+
+## What it doesn't set up
+
+Packages can't carry your personal settings: theme selection, default model
+and provider, API keys (`/login`), and editor keybindings remain yours. Set
+`"theme": "catppuccin-tui-mocha"` in `~/.pi/agent/settings.json` for the full
+effect.
+
+## Updating
+
+```sh
+pi update --extension npm:@nklisch/pi-enhanced
+```
+
+One command refreshes the whole bundle; pin to a version with
+`npm:@nklisch/pi-enhanced@<version>` if you want stability over freshness.

package/node_modules/@ff-labs/pi-fff/README.md

@@ -0,0 +1,153 @@
+# @ff-labs/pi-fff
+
+A [pi](https://github.com/badlogic/pi-mono) extension that replaces the built-in `find` and `grep` tools with [FFF](https://github.com/dmtrKovalenko/fff.nvim) — a Rust-native, SIMD-accelerated file finder with built-in memory.
+
+## What it does
+
+| Built-in tool | pi-fff replacement | Improvement |
+|---|---|---|
+| `find` (spawns `fd`) | `fffind` (FFF `fileSearch`) | Fuzzy matching, frecency ranking, git-aware, pre-indexed |
+| `grep` (spawns `rg`) | `ffgrep` (FFF `grep`) | SIMD-accelerated, frecency-ordered, mmap-cached, no subprocess |
+| *(none)* | `fff-multi-grep` (FFF `multiGrep`) | OR-logic multi-pattern search via Aho-Corasick |
+| `@` file autocomplete (fd-backed) | `@` file autocomplete (FFF-backed, default) | Fuzzy ranking from FFF index/frecency |
+
+### Key advantages over built-in tools
+
+- **No subprocess spawning** — FFF is a Rust native library called through the Node binding. No `fd`/`rg` process per call.
+- **Pre-indexed** — files are indexed in the background at session start. Searches are instant.
+- **Frecency ranking** — files you access often rank higher. Learns across sessions.
+- **Query history** — remembers which files were selected for which queries. Combo boost.
+- **Git-aware** — modified/staged/untracked files are boosted in results.
+- **Smart case** — case-insensitive when query is all lowercase, case-sensitive otherwise.
+- **Fuzzy file search** — `find` uses fuzzy matching, not glob-only. Typo-tolerant.
+- **Cursor pagination** — grep results include a cursor for fetching the next page.
+
+## Install
+
+Requirements:
+- pi
+
+### Install as a pi package
+
+**Via npm (recommended):**
+
+```bash
+pi install npm:@ff-labs/pi-fff
+```
+
+Project-local install:
+
+```bash
+pi install -l npm:@ff-labs/pi-fff
+```
+
+**Via git:**
+
+```bash
+pi install git:github.com/dmtrKovalenko/fff.nvim
+```
+
+Pin to a release:
+
+```bash
+pi install git:github.com/dmtrKovalenko/fff.nvim@v0.3.0
+```
+
+### Local development / manual install
+
+```bash
+git clone https://github.com/dmtrKovalenko/fff.nvim.git
+cd fff.nvim/packages/pi-fff
+npm install
+```
+
+Then add to your pi `settings.json`:
+
+```json
+{
+  "extensions": ["/path/to/fff.nvim/packages/pi-fff/src/index.ts"]
+}
+```
+
+Or test directly:
+
+```bash
+pi -e /path/to/fff.nvim/packages/pi-fff/src/index.ts
+```
+
+This extension registers FFF-powered tools (`fffind`, `ffgrep`, `fff-multi-grep`) alongside pi's built-in tools.
+
+## Tools
+
+### `ffgrep`
+
+Search file contents. Smart case, plain text by default, regex optional.
+
+Parameters:
+- `pattern` — search text or regex
+- `path` — directory/file constraint (e.g. `src/`, `*.ts`)
+- `ignoreCase` — force case-insensitive
+- `literal` — treat as literal string (default: true)
+- `context` — context lines around matches
+- `limit` — max matches (default: 100)
+- `cursor` — pagination cursor from previous result
+
+### `fffind`
+
+Fuzzy file name search. Frecency-ranked.
+
+Parameters:
+- `pattern` — fuzzy query (e.g. `main.ts`, `src/ config`)
+- `path` — directory constraint
+- `limit` — max results (default: 200)
+
+### `fff-multi-grep`
+
+OR-logic multi-pattern content search. SIMD-accelerated Aho-Corasick.
+
+Parameters:
+- `patterns` — array of literal patterns (OR logic)
+- `constraints` — file constraints (e.g. `*.{ts,tsx} !test/`)
+- `context` — context lines
+- `limit` — max matches (default: 100)
+- `cursor` — pagination cursor
+
+## Commands
+
+- `/fff-health` — show FFF status (indexed files, git info, frecency/history DB status)
+- `/fff-rescan` — trigger a file rescan
+- `/fff-mode <mode>` — switch mode (tool name change requires restart)
+
+## Modes
+
+- `tools-and-ui` (default): registers `fffind`, `ffgrep`, `fff-multi-grep` as additional tools + FFF-backed `@` autocomplete
+- `tools-only`: additional tools only; keep pi's default `@` autocomplete
+- `override`: replaces pi's built-in `find`, `grep` and adds `multi_grep` + FFF-backed `@` autocomplete
+
+Mode precedence:
+1. `--fff-mode <mode>` CLI flag
+2. `PI_FFF_MODE=<mode>` environment variable
+3. default (`tools-and-ui`)
+
+## Flags
+
+- `--fff-mode <mode>` — set mode (see above)
+- `--fff-frecency-db <path>` — path to frecency database (also: `FFF_FRECENCY_DB` env)
+- `--fff-history-db <path>` — path to query history database (also: `FFF_HISTORY_DB` env)
+- `--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. Home directory scanning is always enabled for pi.
+
+## Data
+
+When database paths are provided, FFF stores:
+- frecency database — file access frequency/recency
+- history database — query-to-file selection history
+
+No project files are uploaded anywhere by this extension. It runs locally and only uses the configured LLM through pi itself.
+
+## Security
+
+- No shell execution
+- No network calls in the extension code
+- No telemetry
+- No credential handling beyond whatever pi and your configured model provider already do
+- Search state is stored locally under `~/.pi/agent/fff/`

package/node_modules/@ff-labs/pi-fff/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ff-labs/pi-fff",
+  "public": true,
+  "version": "0.10.1",
+  "description": "pi extension: FFF-powered fuzzy file and content search",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmtrKovalenko/fff.git",
+    "directory": "packages/pi-fff"
+  },
+  "homepage": "https://github.com/dmtrKovalenko/fff/tree/main/packages/pi-fff",
+  "bugs": {
+    "url": "https://github.com/dmtrKovalenko/fff/issues"
+  },
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "fff",
+    "search",
+    "grep",
+    "fuzzy-search",
+    "ai-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test test/",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ff-labs/fff-bun": "*",
+    "@ff-labs/fff-node": "*"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/node_modules/@ff-labs/pi-fff/src/aux-finders.ts

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { FileFinderApi } from "@ff-labs/fff-node";
+import { loadSdk, SCAN_TIMEOUT_MS } from "./sdk";
+
+export const MAX_AUX = 3;
+export const IDLE_TTL_MS = 5 * 60 * 1000;
+
+interface AuxPicker {
+  root: string;
+  finder: FileFinderApi;
+  lastUsed: number;
+}
+
+export interface AuxOpts {
+  frecencyDbPath?: string;
+  historyDbPath?: string;
+  enableFsRootScanning: boolean;
+}
+
+export class AuxFinderPool {
+  private entries: AuxPicker[] = [];
+  constructor(private opts: AuxOpts) {}
+
+  destroy(): void {
+    for (const e of this.entries) {
+      e.finder.destroy();
+    }
+
+    this.entries = [];
+  }
+
+  private sweepIdle(now = Date.now()): void {
+    const kept: AuxPicker[] = [];
+    for (const e of this.entries) {
+      if (now - e.lastUsed > IDLE_TTL_MS) {
+        if (!e.finder.isDestroyed) e.finder.destroy();
+      } else {
+        kept.push(e);
+      }
+    }
+    this.entries = kept;
+  }
+
+  async acquire(
+    maybeRoot: string,
+    opts?: { exact?: boolean },
+  ): Promise<{ finder: FileFinderApi; root: string }> {
+    this.sweepIdle();
+    let covering: AuxPicker | null = null;
+    for (const e of this.entries) {
+      if (e.finder.isDestroyed) continue;
+      if (opts?.exact ? e.root !== maybeRoot : !rootCovers(e.root, maybeRoot)) continue;
+      if (!covering || e.root.length > covering.root.length) covering = e;
+    }
+
+    if (covering) {
+      covering.lastUsed = Date.now();
+      return { finder: covering.finder, root: covering.root };
+    }
+
+    if (this.entries.length >= MAX_AUX) {
+      let oldest = this.entries[0];
+      for (const e of this.entries)
+        if (e.lastUsed < oldest.lastUsed) oldest = e;
+      if (!oldest.finder.isDestroyed) oldest.finder.destroy();
+      this.entries = this.entries.filter((e) => e !== oldest);
+    }
+
+    const { FileFinder } = await loadSdk();
+    const result = FileFinder.create({
+      basePath: maybeRoot,
+      frecencyDbPath: this.opts.frecencyDbPath,
+      historyDbPath: this.opts.historyDbPath,
+      aiMode: true,
+      enableHomeDirScanning: true,
+      enableFsRootScanning: this.opts.enableFsRootScanning,
+    });
+    if (!result.ok)
+      throw new Error(
+        `Failed to create aux file finder for ${maybeRoot}: ${result.error}`,
+      );
+
+    await result.value.waitForScan(SCAN_TIMEOUT_MS);
+    this.entries.push({ root: maybeRoot, finder: result.value, lastUsed: Date.now() });
+    return { finder: result.value, root: maybeRoot };
+  }
+
+  size(): number {
+    this.sweepIdle();
+    return this.entries.length;
+  }
+}
+
+// Split an absolute path into an existing directory (the aux root) and a
+// remainder usable as a fuzzy path constraint relative to that root. Glob and
+// nonexistent segments both go into the suffix: we walk up to the nearest
+// existing ancestor so partially-wrong paths still resolve to a search root.
+export function resolveAuxRoot(
+  absPath: string,
+): { root: string; suffix: string } | null {
+  const trimmed = path.normalize(absPath.trim()).replace(/\/+$/, "") || "/";
+  if (!path.isAbsolute(trimmed)) return null;
+  if (trimmed === path.sep) return { root: path.sep, suffix: "" };
+
+  const parts = trimmed.split(path.sep);
+  const firstGlob = parts.findIndex((p) => /[*?[{]/.test(p));
+  const boundary = firstGlob === -1 ? parts.length : firstGlob;
+
+  // Deepest existing non-glob prefix wins; everything below it is suffix.
+  for (let i = boundary; i > 0; i--) {
+    const candidate = parts.slice(0, i).join(path.sep) || path.sep;
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(candidate);
+    } catch {
+      continue;
+    }
+    if (stat.isFile()) {
+      return {
+        root: parts.slice(0, i - 1).join(path.sep) || path.sep,
+        suffix: parts.slice(i - 1).join("/"),
+      };
+    }
+    return { root: candidate, suffix: parts.slice(i).join("/") };
+  }
+  return null;
+}
+
+export function isOutsideWorkspaceRelativePath(relativePath: string): boolean {
+  return (
+    path.isAbsolute(relativePath) ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${path.sep}`)
+  );
+}
+
+// Decide whether a `path` parameter should route to the workspace finder or
+// to an aux finder. Accepts absolute paths, `~`-prefixed paths, and relative
+// paths escaping the workspace (`../other-project`); everything is resolved
+// against cwd first. Returns null to signal "no rerouting" (workspace finder).
+export function routePathConstraint(
+  pathConstraint: string | undefined,
+  cwd: string,
+): { root: string; suffix: string } | null {
+  if (!pathConstraint) return null;
+  let candidate = pathConstraint.trim();
+  if (!candidate) return null;
+  if (candidate === "~" || candidate.startsWith("~/"))
+    candidate = path.join(os.homedir(), candidate.slice(1));
+  if (!path.isAbsolute(candidate)) {
+    // Plain workspace-relative constraints stay on the workspace finder.
+    if (candidate !== ".." && !candidate.startsWith("../")) return null;
+    candidate = path.resolve(cwd, candidate);
+  }
+  const rel = path.relative(cwd, candidate);
+  if (!isOutsideWorkspaceRelativePath(rel)) return null;
+  return resolveAuxRoot(candidate);
+}
+
+
+export function rootCovers(root: string, target: string): boolean {
+  if (root === target) return true;
+  const prefix = root.endsWith(path.sep) ? root : root + path.sep;
+  return target.startsWith(prefix);
+}