pi-repoprompt-cli 0.2.0 → 0.2.6

package/extensions/repoprompt-cli/readcache/LICENSE

@@ -0,0 +1,23 @@
+Derived from pi-readcache (https://github.com/Gurpartap/pi-readcache)
+
+MIT License
+
+Copyright (c) 2026 Gurpartap Singh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/extensions/repoprompt-cli/readcache/constants.ts

@@ -0,0 +1,38 @@
+// readcache/constants.ts - constants for read_file caching via rp-cli
+
+export const RP_READCACHE_META_VERSION = 1 as const;
+export const RP_READCACHE_CUSTOM_TYPE = "repoprompt-cli-readcache" as const;
+
+export const SCOPE_FULL = "full" as const;
+
+export const MAX_DIFF_FILE_BYTES = 2 * 1024 * 1024;
+export const MAX_DIFF_FILE_LINES = 12_000;
+export const MAX_DIFF_TO_BASE_RATIO = 0.9;
+export const MAX_DIFF_TO_BASE_LINE_RATIO = 0.85;
+
+export const DEFAULT_EXCLUDED_PATH_PATTERNS = [
+    ".env*",
+    "*.pem",
+    "*.key",
+    "*.p12",
+    "*.pfx",
+    "*.crt",
+    "*.cer",
+    "*.der",
+    "*.pk8",
+    "id_rsa",
+    "id_ed25519",
+    ".npmrc",
+    ".netrc",
+] as const;
+
+// NOTE: share the same on-disk object store layout as pi-readcache
+export const READCACHE_ROOT_DIR = ".pi/readcache";
+export const READCACHE_OBJECTS_DIR = `${READCACHE_ROOT_DIR}/objects`;
+export const READCACHE_TMP_DIR = `${READCACHE_ROOT_DIR}/tmp`;
+
+export const READCACHE_OBJECT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export function scopeRange(start: number, end: number): `r:${number}:${number}` {
+    return `r:${start}:${end}`;
+}

package/extensions/repoprompt-cli/readcache/diff.ts

@@ -0,0 +1,129 @@
+// readcache/diff.ts - unified diff computation + usefulness gating
+
+import { formatPatch, structuredPatch } from "diff";
+
+import {
+    MAX_DIFF_FILE_BYTES,
+    MAX_DIFF_FILE_LINES,
+    MAX_DIFF_TO_BASE_LINE_RATIO,
+    MAX_DIFF_TO_BASE_RATIO,
+} from "./constants.js";
+
+const PATCH_SEPARATOR_LINE = "===================================================================";
+
+export interface DiffComputation {
+    diffText: string;
+    changedLines: number;
+    addedLines: number;
+    removedLines: number;
+    diffBytes: number;
+}
+
+function sanitizePathForPatch(pathDisplay: string): string {
+    const trimmed = pathDisplay.trim();
+    if (!trimmed) {
+        return "unknown";
+    }
+    return trimmed.replace(/[\t\r\n]/g, "_");
+}
+
+function stripPatchSeparator(patch: string): string {
+    const lines = patch.split("\n");
+    if (lines[0] === PATCH_SEPARATOR_LINE) {
+        return lines.slice(1).join("\n").trimEnd();
+    }
+    return patch.trimEnd();
+}
+
+function lineCount(text: string): number {
+    if (text.length === 0) {
+        return 1;
+    }
+    return text.split("\n").length;
+}
+
+function countChangedLinesFromPatch(diffText: string): { added: number; removed: number } {
+    let added = 0;
+    let removed = 0;
+    for (const line of diffText.split("\n")) {
+        if (!line) {
+            continue;
+        }
+        if (line.startsWith("+++") || line.startsWith("---") || line.startsWith("@@")) {
+            continue;
+        }
+        if (line.startsWith("+")) {
+            added += 1;
+            continue;
+        }
+        if (line.startsWith("-")) {
+            removed += 1;
+        }
+    }
+    return { added, removed };
+}
+
+export function computeUnifiedDiff(
+    baseText: string,
+    currentText: string,
+    pathDisplay: string,
+): DiffComputation | undefined {
+    const safePath = sanitizePathForPatch(pathDisplay);
+    const patch = structuredPatch(`a/${safePath}`, `b/${safePath}`, baseText, currentText, "", "", { context: 3 });
+    if (patch.hunks.length === 0) {
+        return undefined;
+    }
+
+    const diffText = stripPatchSeparator(formatPatch(patch));
+    if (!diffText.includes("@@")) {
+        return undefined;
+    }
+
+    const { added, removed } = countChangedLinesFromPatch(diffText);
+    return {
+        diffText,
+        changedLines: Math.max(added, removed),
+        addedLines: added,
+        removedLines: removed,
+        diffBytes: Buffer.byteLength(diffText, "utf-8"),
+    };
+}
+
+export function isDiffUseful(diffText: string, baseText: string, currentText: string): boolean {
+    if (diffText.trim().length === 0 || !diffText.includes("@@")) {
+        return false;
+    }
+
+    const baseBytes = Buffer.byteLength(baseText, "utf-8");
+    const currentBytes = Buffer.byteLength(currentText, "utf-8");
+    const selectedBytes = Math.max(baseBytes, currentBytes);
+    if (selectedBytes === 0) {
+        return false;
+    }
+
+    if (selectedBytes > MAX_DIFF_FILE_BYTES) {
+        return false;
+    }
+
+    const maxLines = Math.max(lineCount(baseText), lineCount(currentText));
+    if (maxLines > MAX_DIFF_FILE_LINES) {
+        return false;
+    }
+
+    const diffBytes = Buffer.byteLength(diffText, "utf-8");
+    if (diffBytes === 0) {
+        return false;
+    }
+
+    if (diffBytes >= selectedBytes * MAX_DIFF_TO_BASE_RATIO) {
+        return false;
+    }
+
+    const requestedLines = lineCount(currentText);
+    const diffLines = lineCount(diffText);
+    if (diffLines > requestedLines * MAX_DIFF_TO_BASE_LINE_RATIO) {
+        return false;
+    }
+
+    return true;
+}

package/extensions/repoprompt-cli/readcache/meta.ts

@@ -0,0 +1,241 @@
+// readcache/meta.ts - validation + extraction from session entries
+
+import type { SessionEntry } from "@mariozechner/pi-coding-agent";
+
+import { RP_READCACHE_CUSTOM_TYPE, RP_READCACHE_META_VERSION, SCOPE_FULL } from "./constants.js";
+import type {
+    ReadCacheDebugV1,
+    ReadCacheMode,
+    RpReadcacheInvalidationV1,
+    RpReadcacheMetaV1,
+    ScopeKey,
+} from "./types.js";
+
+const RANGE_SCOPE_RE = /^r:(\d+):(\d+)$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function normalizeReadCacheMode(value: unknown): ReadCacheMode | undefined {
+    if (value === "full") return "full";
+    if (value === "unchanged") return "unchanged";
+    if (value === "unchanged_range") return "unchanged_range";
+    if (value === "diff") return "diff";
+    if (value === "baseline_fallback") return "baseline_fallback";
+    return undefined;
+}
+
+function isReadCacheDebugReason(value: unknown): value is ReadCacheDebugV1["reason"] {
+    return (
+        value === "no_base_hash" ||
+        value === "hash_match" ||
+        value === "base_object_missing" ||
+        value === "range_slice_unchanged" ||
+        value === "range_slice_changed" ||
+        value === "diff_file_too_large_bytes" ||
+        value === "diff_file_too_large_lines" ||
+        value === "diff_unavailable_or_empty" ||
+        value === "diff_not_useful" ||
+        value === "diff_payload_truncated" ||
+        value === "diff_emitted" ||
+        value === "bypass_cache"
+    );
+}
+
+function isOptionalBoolean(value: unknown): value is boolean | undefined {
+    return value === undefined || typeof value === "boolean";
+}
+
+function isOptionalPositiveInteger(value: unknown): value is number | undefined {
+    return value === undefined || isPositiveInteger(value);
+}
+
+function isOptionalNonNegativeInteger(value: unknown): value is number | undefined {
+    return value === undefined || isNonNegativeInteger(value);
+}
+
+function isReadCacheDebugV1(value: unknown): value is ReadCacheDebugV1 {
+    if (!isRecord(value)) {
+        return false;
+    }
+
+    if (!isReadCacheDebugReason(value.reason)) {
+        return false;
+    }
+
+    if (value.scope !== "full" && value.scope !== "range") {
+        return false;
+    }
+
+    if (typeof value.baseHashFound !== "boolean" || typeof value.diffAttempted !== "boolean") {
+        return false;
+    }
+
+    return (
+        isOptionalBoolean(value.outsideRangeChanged) &&
+        isOptionalBoolean(value.baseObjectFound) &&
+        isOptionalPositiveInteger(value.largestBytes) &&
+        isOptionalPositiveInteger(value.maxLines) &&
+        isOptionalNonNegativeInteger(value.diffBytes) &&
+        isOptionalNonNegativeInteger(value.diffChangedLines)
+    );
+}
+
+export function isScopeKey(value: unknown): value is ScopeKey {
+    if (value === SCOPE_FULL) {
+        return true;
+    }
+    if (typeof value !== "string") {
+        return false;
+    }
+
+    const match = RANGE_SCOPE_RE.exec(value);
+    if (!match) {
+        return false;
+    }
+
+    const start = Number.parseInt(match[1] ?? "", 10);
+    const end = Number.parseInt(match[2] ?? "", 10);
+
+    return Number.isInteger(start) && Number.isInteger(end) && start > 0 && end >= start;
+}
+
+function parseMetaV1(value: unknown): RpReadcacheMetaV1 | undefined {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+
+    if (value.v !== RP_READCACHE_META_VERSION) {
+        return undefined;
+    }
+
+    if (value.tool !== "read_file") {
+        return undefined;
+    }
+
+    if (typeof value.pathKey !== "string" || value.pathKey.length === 0) {
+        return undefined;
+    }
+
+    if (!isScopeKey(value.scopeKey)) {
+        return undefined;
+    }
+
+    if (typeof value.servedHash !== "string" || value.servedHash.length === 0) {
+        return undefined;
+    }
+
+    const mode = normalizeReadCacheMode(value.mode);
+    if (!mode) {
+        return undefined;
+    }
+
+    const requiresBaseHash = mode === "unchanged" || mode === "unchanged_range" || mode === "diff";
+    if (requiresBaseHash) {
+        if (typeof value.baseHash !== "string" || value.baseHash.length === 0) {
+            return undefined;
+        }
+    } else if (value.baseHash !== undefined && (typeof value.baseHash !== "string" || value.baseHash.length === 0)) {
+        return undefined;
+    }
+
+    if (
+        !isPositiveInteger(value.totalLines) ||
+        !isPositiveInteger(value.rangeStart) ||
+        !isPositiveInteger(value.rangeEnd) ||
+        value.rangeEnd < value.rangeStart ||
+        !isNonNegativeInteger(value.bytes) ||
+        (value.debug !== undefined && !isReadCacheDebugV1(value.debug))
+    ) {
+        return undefined;
+    }
+
+    return {
+        v: RP_READCACHE_META_VERSION,
+        tool: "read_file",
+        pathKey: value.pathKey,
+        scopeKey: value.scopeKey,
+        servedHash: value.servedHash,
+        ...(typeof value.baseHash === "string" ? { baseHash: value.baseHash } : {}),
+        mode,
+        totalLines: value.totalLines,
+        rangeStart: value.rangeStart,
+        rangeEnd: value.rangeEnd,
+        bytes: value.bytes,
+        ...(value.debug !== undefined ? { debug: value.debug } : {}),
+    };
+}
+
+export function buildRpReadcacheMetaV1(meta: Omit<RpReadcacheMetaV1, "v" | "tool">): RpReadcacheMetaV1 {
+    return {
+        v: RP_READCACHE_META_VERSION,
+        tool: "read_file",
+        ...meta,
+    };
+}
+
+export function isRpReadcacheInvalidationV1(value: unknown): value is RpReadcacheInvalidationV1 {
+    if (!isRecord(value)) {
+        return false;
+    }
+
+    return (
+        value.v === RP_READCACHE_META_VERSION &&
+        value.kind === "invalidate" &&
+        value.tool === "read_file" &&
+        typeof value.pathKey === "string" &&
+        value.pathKey.length > 0 &&
+        isScopeKey(value.scopeKey) &&
+        isPositiveInteger(value.at)
+    );
+}
+
+export function buildInvalidationV1(pathKey: string, scopeKey: ScopeKey, at = Date.now()): RpReadcacheInvalidationV1 {
+    return {
+        v: RP_READCACHE_META_VERSION,
+        kind: "invalidate",
+        tool: "read_file",
+        pathKey,
+        scopeKey,
+        at,
+    };
+}
+
+export function extractReadMetaFromSessionEntry(entry: SessionEntry): RpReadcacheMetaV1 | undefined {
+    if (entry.type !== "message") {
+        return undefined;
+    }
+
+    const message = entry.message;
+    if (message.role !== "toolResult" || message.toolName !== "rp_exec") {
+        return undefined;
+    }
+
+    if (!isRecord(message.details)) {
+        return undefined;
+    }
+
+    const candidate = (message.details as Record<string, unknown>).rpReadcache;
+    return parseMetaV1(candidate);
+}
+
+export function extractInvalidationFromSessionEntry(entry: SessionEntry): RpReadcacheInvalidationV1 | undefined {
+    if (entry.type !== "custom" || entry.customType !== RP_READCACHE_CUSTOM_TYPE) {
+        return undefined;
+    }
+
+    if (!isRpReadcacheInvalidationV1(entry.data)) {
+        return undefined;
+    }
+
+    return entry.data;
+}

package/extensions/repoprompt-cli/readcache/object-store.ts

@@ -0,0 +1,184 @@
+// readcache/object-store.ts - content-addressed storage for file snapshots
+
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { access, mkdir, open, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { READCACHE_OBJECT_MAX_AGE_MS, READCACHE_OBJECTS_DIR, READCACHE_TMP_DIR } from "./constants.js";
+
+const HASH_HEX_RE = /^[a-f0-9]{64}$/;
+
+export interface ObjectStoreStats {
+    objects: number;
+    bytes: number;
+}
+
+export interface PruneObjectsResult {
+    scanned: number;
+    deleted: number;
+    cutoffMs: number;
+}
+
+function ensureValidHash(hash: string): void {
+    if (!HASH_HEX_RE.test(hash)) {
+        throw new Error(`Invalid sha256 hash "${hash}"`);
+    }
+}
+
+function isObjectFileName(name: string): boolean {
+    return name.startsWith("sha256-") && name.endsWith(".txt");
+}
+
+export function hashBytes(buffer: Buffer): string {
+    return createHash("sha256").update(buffer).digest("hex");
+}
+
+export function objectPathForHash(repoRoot: string, hash: string): string {
+    ensureValidHash(hash);
+    return join(repoRoot, READCACHE_OBJECTS_DIR, `sha256-${hash}.txt`);
+}
+
+async function ensureStoreDirs(repoRoot: string): Promise<{ objectsDir: string; tmpDir: string }> {
+    const objectsDir = join(repoRoot, READCACHE_OBJECTS_DIR);
+    const tmpDir = join(repoRoot, READCACHE_TMP_DIR);
+
+    await mkdir(objectsDir, { recursive: true, mode: 0o700 });
+    await mkdir(tmpDir, { recursive: true, mode: 0o700 });
+
+    return { objectsDir, tmpDir };
+}
+
+async function exists(filePath: string): Promise<boolean> {
+    try {
+        await access(filePath, constants.F_OK);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export async function persistObjectIfAbsent(repoRoot: string, hash: string, text: string): Promise<void> {
+    ensureValidHash(hash);
+
+    const { tmpDir } = await ensureStoreDirs(repoRoot);
+    const objectPath = objectPathForHash(repoRoot, hash);
+
+    if (await exists(objectPath)) {
+        return;
+    }
+
+    const tempPath = join(
+        tmpDir,
+        `sha256-${hash}-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`,
+    );
+    let tempFileCreated = false;
+
+    try {
+        const handle = await open(tempPath, "wx", 0o600);
+        tempFileCreated = true;
+        try {
+            await handle.writeFile(text, "utf-8");
+            await handle.sync();
+        } finally {
+            await handle.close();
+        }
+
+        await rename(tempPath, objectPath);
+    } catch (error) {
+        const errorCode = (error as NodeJS.ErrnoException).code;
+
+        if (errorCode === "EEXIST") {
+            if (tempFileCreated && (await exists(tempPath))) {
+                await unlink(tempPath);
+            }
+            return;
+        }
+
+        if (tempFileCreated && (await exists(tempPath))) {
+            await unlink(tempPath);
+        }
+
+        throw error;
+    }
+}
+
+export async function loadObject(repoRoot: string, hash: string): Promise<string | undefined> {
+    ensureValidHash(hash);
+    const objectPath = objectPathForHash(repoRoot, hash);
+
+    try {
+        return await readFile(objectPath, "utf-8");
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+
+export async function getStoreStats(repoRoot: string): Promise<ObjectStoreStats> {
+    const { objectsDir } = await ensureStoreDirs(repoRoot);
+    const entries = await readdir(objectsDir, { withFileTypes: true });
+
+    let objects = 0;
+    let bytes = 0;
+
+    for (const entry of entries) {
+        if (!entry.isFile() || !isObjectFileName(entry.name)) {
+            continue;
+        }
+
+        objects += 1;
+        const info = await stat(join(objectsDir, entry.name));
+        bytes += info.size;
+    }
+
+    return { objects, bytes };
+}
+
+export async function pruneObjectsOlderThan(
+    repoRoot: string,
+    maxAgeMs = READCACHE_OBJECT_MAX_AGE_MS,
+    nowMs = Date.now(),
+): Promise<PruneObjectsResult> {
+    if (!Number.isFinite(maxAgeMs) || maxAgeMs < 0) {
+        throw new Error(`Invalid maxAgeMs "${String(maxAgeMs)}"`);
+    }
+
+    const { objectsDir } = await ensureStoreDirs(repoRoot);
+    const entries = await readdir(objectsDir, { withFileTypes: true });
+    const cutoffMs = nowMs - maxAgeMs;
+
+    let scanned = 0;
+    let deleted = 0;
+
+    for (const entry of entries) {
+        if (!entry.isFile() || !isObjectFileName(entry.name)) {
+            continue;
+        }
+
+        scanned += 1;
+        const filePath = join(objectsDir, entry.name);
+
+        let info;
+        try {
+            info = await stat(filePath);
+        } catch {
+            continue;
+        }
+
+        if (info.mtimeMs > cutoffMs) {
+            continue;
+        }
+
+        try {
+            await unlink(filePath);
+            deleted += 1;
+        } catch {
+            // Fail-open
+        }
+    }
+
+    return { scanned, deleted, cutoffMs };
+}