pi-repoprompt-cli 0.2.0 → 0.2.5

package/README.md

@@ -6,8 +6,14 @@ Provides two tools:
 - `rp_bind` — bind a RepoPrompt window + compose tab (routing)
 - `rp_exec` — run `rp-cli -e <cmd>` against that binding (quiet defaults + output truncation)
 
-Also provides a convenience command:
+Optional:
+- [Gurpartap/pi-readcache](https://github.com/Gurpartap/pi-readcache)-like caching for `rp_exec` calls that read files (`read` / `cat` / `read_file`) to save on tokens
+  - returns unchanged markers and diffs on repeat reads
+
+Also provides convenience commands:
 - `/rpbind <window_id> <tab>`
+- `/rpcli-readcache-status`
+- `/rpcli-readcache-refresh <path> [start-end]`
 
 ## Install
 
@@ -26,7 +32,7 @@ Add to `~/.pi/agent/settings.json` (or replace an existing unfiltered `git:githu
   "packages": [
     {
       "source": "git:github.com/w-winter/dot314",
-      "extensions": ["extensions/repoprompt-cli.ts"],
+      "extensions": ["extensions/repoprompt-cli/index.ts"],
       "skills": [],
       "themes": [],
       "prompts": []
@@ -39,6 +45,18 @@ Add to `~/.pi/agent/settings.json` (or replace an existing unfiltered `git:githu
 
 - `rp-cli` must be installed and available on `PATH`
 
+## Configuration
+
+Enable readcache (optional):
+
+Create `~/.pi/agent/extensions/repoprompt-cli/config.json`:
+
+```json
+{
+  "readcacheReadFile": true
+}
+```
+
 ## Quick start
 
 1) Find your RepoPrompt window + tab (from a terminal):
@@ -60,6 +78,30 @@ rp-cli -e "workspace tabs"
 Use rp_exec with cmd: "get_file_tree type=files max_depth=4".
 ```
 
+If `readcacheReadFile` is enabled, repeat reads can be token-optimized:
+
+```text
+Use rp_exec with cmd: "read path=src/main.ts start_line=1 limit=120".
+```
+
+To force baseline output for a specific read:
+
+```text
+Use rp_exec with cmd: "read path=src/main.ts start_line=1 limit=120 bypass_cache=true".
+```
+
+Notes:
+- Readcache only triggers for **single-command** reads. Compound commands (`&&`, `;`, `|`) fail open to baseline output
+- When `just-bash` AST parsing is unavailable, caching only applies to unquoted/unescaped single-command reads; quoted/escaped forms fail open
+- `rawJson=true` disables caching
+
+## Readcache gotchas
+
+- `rawJson=true` disables readcache. Don't use unless debugging
+- Need full content? rerun with `bypass_cache=true`
+- Single-command reads only (no `&&` / `;` / `|`)
+- Multi-root: use absolute or specific relative paths
+
 ## Safety behavior (by default)
 
 - Blocks delete-like commands unless `allowDelete: true`

package/extensions/repoprompt-cli/README.md

@@ -0,0 +1,94 @@
+# RepoPrompt CLI extension for Pi (`repoprompt-cli`)
+
+This folder contains the Pi extension that integrates the **RepoPrompt CLI** (`rp-cli`) into Pi.
+
+It provides two Pi tools:
+
+- `rp_bind` — bind to a specific RepoPrompt **window id** + **compose tab** (routing)
+- `rp_exec` — run `rp-cli -e <cmd>` against that binding
+
+## Optional: readcache for `rp_exec read`
+
+If enabled, `rp_exec` will apply [Gurpartap/pi-readcache](https://github.com/Gurpartap/pi-readcache)-like token savings for single-command file reads, returning:
+
+- an *unchanged marker* on repeat reads, or
+- a *unified diff* when a reread changed and the diff is small/useful, otherwise
+- baseline output (fail-open)
+
+### Enable
+
+Create:
+
+- `~/.pi/agent/extensions/repoprompt-cli/config.json`
+
+```json
+{
+  "readcacheReadFile": true
+}
+```
+
+Note: when enabled, the extension may persist UTF-8 file snapshots to an on-disk content-addressed store under
+`<repo-root>/.pi/readcache/objects` to compute diffs/unchanged markers across calls. Common secret filenames (e.g. `.env*`, `*.pem`) are excluded,
+but this is best-effort
+
+### Supported read forms (cached)
+
+Caching only triggers when `cmd` is a **single** read-like invocation (no chains / pipes):
+
+- `read <path> [start] [limit]`
+- `read <path> -N` (tail)
+- `cat <path> [start] [limit]`
+- `read_file path=<path> start_line=<n> limit=<n>`
+- slice suffix: `read <path>:<start>-<end>` (or `path=<path>:<start>-<end>`)
+
+### Bypass for a single call
+
+Add `bypass_cache=true` to the `cmd`:
+
+```text
+rp_exec cmd="read path=src/main.ts start_line=1 limit=120 bypass_cache=true"
+```
+
+## Readcache gotchas
+
+- `rawJson=true` disables readcache. Don't use unless debugging
+- Need full content? rerun with `bypass_cache=true`
+- Single-command reads only (no `&&` / `;` / `|`)
+- Multi-root: use absolute or specific relative paths
+
+### When caching will NOT trigger
+
+`rp_exec` intentionally fails open to baseline output when parsing is ambiguous or unsafe. Caching is disabled for:
+
+- **fallback parser limitation**: when `just-bash` AST parsing is unavailable, only unquoted/unescaped single-command reads are parsed for caching. Quoted/escaped forms (e.g. paths with spaces) will fail open to baseline output
+
+- compound commands: `&&`, `;`, pipelines (`|`)
+- multiple top-level invocations in one `cmd`
+- `rawJson=true`
+- unbound execution (no window/tab)
+- read requests with unknown flags/args that prevent canonicalization
+
+## Slash commands
+
+These are **Pi slash commands** (for the chat UI), not `rp_exec` commands:
+
+- `/rpbind <window_id> <tab>`
+- `/rpcli-readcache-status`
+- `/rpcli-readcache-refresh <path> [start-end]`
+
+## Smoke test
+
+1) Bind:
+
+```text
+/rpbind 4 Compose
+```
+
+2) Read the same range twice:
+
+```text
+Use rp_exec with cmd: "read src/main.ts 1 40".
+Use rp_exec with cmd: "read src/main.ts 1 40".
+```
+
+The second call should return a `[readcache: ...]` marker.

package/extensions/repoprompt-cli/config.json.example

@@ -0,0 +1,3 @@
+{
+  "readcacheReadFile": true
+}

package/extensions/repoprompt-cli/config.ts

@@ -0,0 +1,47 @@
+// config.ts - configuration loading for the repoprompt-cli extension
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import type { RpCliConfig } from "./types.js";
+
+const DEFAULT_CONFIG: Required<RpCliConfig> = {
+    readcacheReadFile: false,
+};
+
+const CONFIG_LOCATIONS = [
+    () => path.join(os.homedir(), ".pi", "agent", "extensions", "repoprompt-cli", "config.json"),
+];
+
+function tryReadJson<T>(filePath: string): T | null {
+    try {
+        const content = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(content) as T;
+    } catch {
+        return null;
+    }
+}
+
+export function loadConfig(overrides?: Partial<RpCliConfig>): Required<RpCliConfig> {
+    let config: Required<RpCliConfig> = { ...DEFAULT_CONFIG };
+
+    for (const getPath of CONFIG_LOCATIONS) {
+        const candidate = getPath();
+        if (!fs.existsSync(candidate)) {
+            continue;
+        }
+
+        const fileConfig = tryReadJson<Partial<RpCliConfig>>(candidate);
+        if (fileConfig) {
+            config = { ...config, ...fileConfig };
+            break;
+        }
+    }
+
+    if (overrides) {
+        config = { ...config, ...overrides };
+    }
+
+    return config;
+}