pi-diff-widget 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2026-10-12
+
+### Changed
+
+- README: document the `/diff-widget` actions (`on`, `off`, `accept`, `reject`)
+  as a table, link them from the `/diff` usage section, and correct the
+  local-checkout path in the install block.
+
+## [0.1.1] - 2026-09-25
+
+### Fixed
+
+- A tracked file whose parent directory disappeared no longer reports as a
+  whole-file deletion in the edits widget. Such baselines are dropped, so
+  `/diff-widget reject` can no longer rebuild a directory that was moved or
+  deleted. Files the agent actually deleted still count, and `reject` still
+  recreates them.
+
+## [0.1.0] - 2026-09-25
+
+First release.
+
+### Added
+
+- `/diff` command: a scrollable overlay with uncommitted changes and per-turn
+  edits. `Tab` toggles sources, `[` and `]` step turns, `n` and `p` jump files.
+- Uncommitted view from git, including repos with no commits, with handling for
+  binary, oversized, and unreadable files.
+- Per-turn view reconstructed from session data. `edit` diffs come from
+  `details.diff`; `write` diffs are synthesized from before/after snapshots and
+  persisted so they survive a reload.
+- Live edits widget above the editor showing net agent changes against a
+  per-file session baseline. A file leaves the panel once it is committed.
+- `/diff-widget` command: `on`, `off`, `accept` (alias `keep`) to keep the
+  changes, and `reject` to restore files to their pre-agent content. Unknown
+  actions warn instead of silently toggling.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omgzsa
+
+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/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# pi-diff-widget
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interactive diff viewer and live edits widget for [pi](https://pi.dev).
+
+## Install
+
+```bash
+pi install npm:pi-diff-widget
+# straight from the repo, no npm required
+pi install git:github.com/omgzsa/pi-diff-widget
+# or from a local checkout
+pi install /absolute/path/to/pi-diff-widget
+```
+
+## Usage
+
+```
+/diff
+```
+
+Opens a scrollable overlay with two sources:
+
+- **Uncommitted**: tracked modifications, staged changes, deletions, and
+  untracked files from `git diff HEAD`.
+- **Turns**: the files the agent edited, grouped by the prompt that caused them.
+  Read straight from the session, so it needs no git and works anywhere.
+
+Diffs render with pi's own renderer, so colors and intra-line highlighting match
+the inline edit diffs.
+
+Keys:
+
+- `Tab`: switch between uncommitted and turns
+- `[` / `]`: previous / next turn (turns view)
+- `up` / `down`: scroll one line
+- `pageUp` / `pageDown`: scroll one page
+- `n` / `p`: next / previous file or section
+- `g` / `G`: jump to top / bottom
+- `q` / `Esc`: close
+
+See [Live edits widget](#live-edits-widget) for the `/diff-widget` actions
+(`on`, `off`, `accept`, `reject`).
+
+## Live edits widget
+
+Above the editor, pi-diff shows the net effect of the agent's edits this
+session, refreshed at each turn boundary:
+
+```
+edits · 3 files · +3 -0
+src/git.ts      +1 -0
+src/index.ts    +1 -0
+src/ui.ts       +1 -0
+```
+
+For each file the agent touches, pi-diff records the content before the first
+touch and diffs it against the current content. Reverted files drop out and the
+counts are net, so it shows what the agent has actually changed, not cumulative
+churn. Committing a file drops it from the panel automatically, so what remains
+is the agent's work that is not yet committed. Paths are shown relative to the
+working directory. Baselines live in the session, capped at 256 KB per file. A
+baseline whose parent directory no longer exists is dropped, so a checkout you
+move or delete stops counting as a whole-file deletion.
+
+It hides itself when nothing differs.
+
+### `/diff-widget` actions
+
+| Command | Effect |
+|---|---|
+| `/diff-widget` | Toggle the panel. With no argument it shows a hidden panel and hides a visible one |
+| `/diff-widget on` | Show it |
+| `/diff-widget off` | Hide it |
+| `/diff-widget accept` | Keep the agent's edits: the current content becomes the baseline and the panel clears. Alias: `keep` |
+| `/diff-widget reject` | Undo the agent's edits: restore every tracked file to its pre-agent content, delete the files the agent created, and recreate the ones it deleted |
+
+`accept` is Zed's Keep All. `reject` asks for confirmation first, naming up to
+five affected paths, and cannot be undone. Whole files only: there is no
+hunk-level accept or reject. With nothing to reject it reports `Nothing to
+reject`, and any unrecognized argument warns instead of toggling the panel, so a
+typo never hides the widget by accident.
+
+```
+/diff-widget
+/diff-widget on
+/diff-widget accept
+/diff-widget reject
+```
+
+## Status
+
+- [x] Uncommitted changes (`git diff HEAD` plus untracked files)
+- [x] Per-turn diffs grouped by prompt, reconstructed from session edit results
+- [x] `write`-tool before/after snapshots, persisted per turn
+- [x] Live net edits widget above the editor, with `/diff-widget on|off|accept|reject`
+
+See [ROADMAP.md](./ROADMAP.md) for planned work and known gaps.
+
+## How it works
+
+- Uncommitted diffs shell out to git, then feed old and new content into pi's
+  `generateDiffString` and `renderDiff`. No third-party diff library.
+- Per-turn diffs read pi's session data. The `edit` tool persists `details.diff`
+  per call, so reconstruction needs no git and works outside a repo. The `write`
+  tool stores no diff, so a `tool_call` handler snapshots the old content,
+  synthesizes one on `tool_result`, and appends it to the session at `turn_end`.
+  Write diffs therefore survive reload, same as edit diffs.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+pi -e ./src/index.ts   # then run /diff
+```
+
+Tests use the built-in `node:test` runner with no extra dependencies. Git tests
+build throwaway repos under the system temp directory.

package/package.json

@@ -1,6 +1,51 @@
 {
-  "name": "pi-diff-widget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "pi-diff-widget",
+    "version": "0.1.2",
+    "description": "Interactive diff viewer for pi: uncommitted changes and per-turn diffs",
+    "keywords": [
+        "pi-package",
+        "pi",
+        "diff",
+        "git"
+    ],
+    "license": "MIT",
+    "author": "omgzsa",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/omgzsa/pi-diff-widget.git"
+    },
+    "homepage": "https://github.com/omgzsa/pi-diff-widget#readme",
+    "bugs": {
+        "url": "https://github.com/omgzsa/pi-diff-widget/issues"
+    },
+    "type": "module",
+    "files": [
+        "src",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE"
+    ],
+    "pi": {
+        "extensions": [
+            "./src/index.ts"
+        ]
+    },
+    "scripts": {
+        "typecheck": "tsc --noEmit",
+        "test": "node --experimental-strip-types --test test/*.test.ts",
+        "prepublishOnly": "npm run typecheck && npm test"
+    },
+    "engines": {
+        "node": ">=22.19.0"
+    },
+    "peerDependencies": {
+        "@earendil-works/pi-coding-agent": "*",
+        "@earendil-works/pi-tui": "*"
+    },
+    "devDependencies": {
+        "@earendil-works/pi-coding-agent": "^0.85.1",
+        "@earendil-works/pi-tui": "^0.85.1",
+        "@types/node": "^22.0.0",
+        "typescript": "^5.6.0"
+    }
+}

package/src/baseline.ts

@@ -0,0 +1,180 @@
+import { readFile, stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { isToolCallEventType } from '@earendil-works/pi-coding-agent';
+import type {
+    ExtensionAPI,
+    SessionEntry,
+} from '@earendil-works/pi-coding-agent';
+
+export const BASELINE_ENTRY = 'pi-diff:baselines';
+const MAX_BASELINE_BYTES = 256 * 1024;
+
+export interface BaselineRecord {
+    path: string;
+    content: string;
+    /** True when the file did not exist when the baseline was captured. */
+    missing?: boolean;
+}
+
+export interface BaselineRead {
+    content: string;
+    existed: boolean;
+}
+
+/**
+ * Read a file for baselining. `existed` distinguishes a missing file (empty
+ * baseline) from a genuinely empty file, which reject needs in order to delete
+ * versus empty. Returns undefined when the file is too large or unreadable.
+ */
+export async function readBaseline(
+    path: string,
+    maxBytes = MAX_BASELINE_BYTES,
+): Promise<BaselineRead | undefined> {
+    const info = await stat(path).catch(() => undefined);
+    if (!info || !info.isFile()) return { content: '', existed: false };
+    if (info.size > maxBytes) return undefined;
+    const content = await readFile(path, 'utf8').catch(() => undefined);
+    if (content === undefined) return undefined;
+    return { content, existed: true };
+}
+
+/** Content only, for callers that do not care whether the file existed. */
+export async function readFileCapped(
+    path: string,
+    maxBytes = MAX_BASELINE_BYTES,
+): Promise<string | undefined> {
+    return (await readBaseline(path, maxBytes))?.content;
+}
+
+/**
+ * True when the path's parent directory is gone. A tracked path whose location
+ * no longer exists; the checkout moved or was removed, so its baseline must
+ * not read as a deletion.
+ */
+export async function locationGone(path: string): Promise<boolean> {
+    const info = await stat(dirname(path)).catch(() => undefined);
+    return info?.isDirectory() !== true;
+}
+
+/**
+ * Records each file's content the first time the agent touches it, so net agent
+ * changes can be diffed against the pre-agent state. Independent of git.
+ */
+export class BaselineTracker {
+    private readonly baselines = new Map<string, string>();
+    private readonly missing = new Set<string>();
+    private readonly unflushed = new Set<string>();
+
+    get(path: string): string | undefined {
+        return this.baselines.get(path);
+    }
+
+    paths(): string[] {
+        return [...this.baselines.keys()];
+    }
+
+    /** True when the path did not exist before the agent first touched it. */
+    wasMissing(path: string): boolean {
+        return this.missing.has(path);
+    }
+
+    async capture(cwd: string, path: string): Promise<void> {
+        const absolute = resolve(cwd, path);
+        if (this.baselines.has(absolute)) return;
+        const read = await readBaseline(absolute);
+        if (read === undefined) return;
+        this.store(absolute, read);
+        this.unflushed.add(absolute);
+    }
+
+    /** Accept current content as the new baseline, so net changes drop to zero. */
+    async rebaseline(pi: ExtensionAPI): Promise<void> {
+        for (const path of [...this.baselines.keys()]) {
+            const read = await readBaseline(path);
+            if (read === undefined) continue;
+            this.store(path, read);
+            this.unflushed.add(path);
+        }
+        this.flush(pi);
+    }
+
+    /** Drop baselines whose absolute path fails the predicate. */
+    retain(keep: (path: string) => boolean): void {
+        for (const path of [...this.baselines.keys()]) {
+            if (!keep(path)) {
+                this.baselines.delete(path);
+                this.missing.delete(path);
+            }
+        }
+    }
+
+    private store(path: string, read: BaselineRead): void {
+        this.baselines.set(path, read.content);
+        if (read.existed) this.missing.delete(path);
+        else this.missing.add(path);
+    }
+
+    flush(pi: ExtensionAPI): void {
+        if (this.unflushed.size === 0) return;
+        const records: BaselineRecord[] = [];
+        for (const path of this.unflushed) {
+            const content = this.baselines.get(path);
+            if (content === undefined) continue;
+            records.push({
+                path,
+                content,
+                missing: this.missing.has(path) ? true : undefined,
+            });
+        }
+        this.unflushed.clear();
+        if (records.length > 0) {
+            pi.appendEntry(BASELINE_ENTRY, { baselines: records });
+        }
+    }
+
+    load(branch: SessionEntry[]): void {
+        for (const entry of branch) {
+            if (
+                entry.type !== 'custom' ||
+                entry.customType !== BASELINE_ENTRY
+            ) {
+                continue;
+            }
+            const records = (
+                entry.data as { baselines?: BaselineRecord[] } | undefined
+            )?.baselines;
+            if (!Array.isArray(records)) continue;
+            for (const record of records) {
+                // Later entries win, so accepting can re-baseline a path.
+                this.store(record.path, {
+                    content: record.content,
+                    existed: record.missing !== true,
+                });
+            }
+        }
+    }
+}
+
+export function createBaselineTracker(pi: ExtensionAPI): BaselineTracker {
+    const tracker = new BaselineTracker();
+
+    pi.on('session_start', (_event, ctx) => {
+        tracker.load(ctx.sessionManager.getBranch());
+    });
+
+    pi.on('tool_call', async (event, ctx) => {
+        if (isToolCallEventType('edit', event)) {
+            await tracker.capture(ctx.cwd, event.input.path);
+            return;
+        }
+        if (isToolCallEventType('write', event)) {
+            await tracker.capture(ctx.cwd, event.input.path);
+        }
+    });
+
+    // Flush at turn boundaries, where it is safe to append a session entry.
+    pi.on('turn_end', () => tracker.flush(pi));
+    pi.on('agent_settled', () => tracker.flush(pi));
+
+    return tracker;
+}

package/src/document.ts

@@ -0,0 +1,50 @@
+import { renderDiff } from '@earendil-works/pi-coding-agent';
+import type { Theme } from '@earendil-works/pi-coding-agent';
+import type { DiffSection } from './view.ts';
+
+/** The theme methods `buildDocument` uses. */
+export type DocumentTheme = Pick<Theme, 'fg' | 'bold'>;
+
+/** Turns one raw display diff into styled, newline-joined lines. */
+export type DiffTextRenderer = (diff: string) => string;
+
+export interface DiffDocument {
+    lines: string[];
+    sectionStarts: number[];
+}
+
+/**
+ * Flatten sections into one scrollable document. Pure and TUI-free. The body
+ * renderer is injected so tests avoid pi's global theme; defaults to renderDiff.
+ */
+export function buildDocument(
+    sections: DiffSection[],
+    theme: DocumentTheme,
+    renderDiffText: DiffTextRenderer = renderDiff,
+): DiffDocument {
+    const lines: string[] = [];
+    const sectionStarts: number[] = [];
+
+    if (sections.length === 0) {
+        lines.push(theme.fg('dim', 'No changes to show.'));
+        return { lines, sectionStarts };
+    }
+
+    for (const section of sections) {
+        sectionStarts.push(lines.length);
+        const detail = section.detail
+            ? `  ${theme.fg('dim', section.detail)}`
+            : '';
+        lines.push(`${theme.fg('accent', theme.bold(section.title))}${detail}`);
+        if (section.diff) {
+            for (const line of renderDiffText(section.diff).split('\n')) {
+                lines.push(line);
+            }
+        } else {
+            lines.push(theme.fg('dim', section.note ?? '(no textual diff)'));
+        }
+        lines.push('');
+    }
+
+    return { lines, sectionStarts };
+}

package/src/exec.ts

@@ -0,0 +1,8 @@
+import type { ExecOptions, ExecResult } from '@earendil-works/pi-coding-agent';
+
+/** The subset of `ExtensionAPI` used to shell out. */
+export type ExecFn = (
+    command: string,
+    args: string[],
+    options?: ExecOptions,
+) => Promise<ExecResult>;

package/src/git.ts

@@ -0,0 +1,198 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { generateDiffString } from '@earendil-works/pi-coding-agent';
+import type { ExecResult } from '@earendil-works/pi-coding-agent';
+import type { ExecFn } from './exec.ts';
+
+export type FileStatus =
+    | 'added'
+    | 'modified'
+    | 'deleted'
+    | 'binary'
+    | 'too-large'
+    | 'unreadable';
+
+export interface DiffFile {
+    path: string;
+    status: FileStatus;
+    /** Raw display diff in pi's line-numbered format (`+123 text`). Render with `renderDiff`. */
+    diff: string;
+}
+
+const MAX_TEXT_BYTES = 512 * 1024;
+const MAX_DIFF_LINES = 4000;
+
+function splitNul(value: string): string[] {
+    return value.split('\0').filter((part) => part.length > 0);
+}
+
+function looksBinary(text: string): boolean {
+    return text.includes('\0');
+}
+
+function capLines(text: string): string {
+    const lines = text.split('\n');
+    if (lines.length <= MAX_DIFF_LINES) return text;
+    const kept = lines.slice(0, MAX_DIFF_LINES);
+    kept.push(`... ${lines.length - MAX_DIFF_LINES} more lines`);
+    return kept.join('\n');
+}
+
+async function runGit(
+    exec: ExecFn,
+    cwd: string,
+    args: string[],
+): Promise<ExecResult> {
+    return exec('git', args, { cwd });
+}
+
+async function readHead(
+    exec: ExecFn,
+    cwd: string,
+    path: string,
+): Promise<string | undefined> {
+    const result = await runGit(exec, cwd, ['show', `HEAD:${path}`]);
+    return result.code === 0 ? result.stdout : undefined;
+}
+
+type WorktreeRead =
+    | { kind: 'text'; text: string }
+    | { kind: 'missing' }
+    | { kind: 'binary' }
+    | { kind: 'too-large' }
+    | { kind: 'unreadable' };
+
+async function readWorktree(absolutePath: string): Promise<WorktreeRead> {
+    try {
+        const buffer = await readFile(absolutePath);
+        if (buffer.byteLength > MAX_TEXT_BYTES) return { kind: 'too-large' };
+        if (buffer.includes(0)) return { kind: 'binary' };
+        return { kind: 'text', text: buffer.toString('utf8') };
+    } catch (error) {
+        // Only ENOENT means the file is gone. Anything else is a read failure.
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return { kind: 'missing' };
+        }
+        return { kind: 'unreadable' };
+    }
+}
+
+interface ChangedPaths {
+    hasHead: boolean;
+    paths: Set<string>;
+}
+
+/** Changed paths relative to `cwd`, or undefined when not in a git repository. */
+async function collectChangedPaths(
+    exec: ExecFn,
+    cwd: string,
+): Promise<ChangedPaths | undefined> {
+    const insideRepo = await runGit(exec, cwd, [
+        'rev-parse',
+        '--is-inside-work-tree',
+    ]);
+    if (insideRepo.code !== 0 || insideRepo.stdout.trim() !== 'true') {
+        return undefined;
+    }
+
+    const hasHead =
+        (await runGit(exec, cwd, ['rev-parse', '--verify', 'HEAD'])).code === 0;
+
+    const paths = new Set<string>();
+    if (hasHead) {
+        const tracked = await runGit(exec, cwd, [
+            'diff',
+            '--name-only',
+            '-z',
+            '--no-renames',
+            'HEAD',
+        ]);
+        if (tracked.code !== 0) {
+            throw new Error(tracked.stderr.trim() || 'git diff failed');
+        }
+        for (const path of splitNul(tracked.stdout)) paths.add(path);
+        const untracked = await runGit(exec, cwd, [
+            'ls-files',
+            '--others',
+            '--exclude-standard',
+            '-z',
+        ]);
+        for (const path of splitNul(untracked.stdout)) paths.add(path);
+    } else {
+        // No commits yet: every staged or untracked file is new.
+        const all = await runGit(exec, cwd, [
+            'ls-files',
+            '--cached',
+            '--others',
+            '--exclude-standard',
+            '-z',
+        ]);
+        for (const path of splitNul(all.stdout)) paths.add(path);
+    }
+
+    return { hasHead, paths };
+}
+
+/**
+ * Relative paths with uncommitted changes, or undefined when `cwd` is not a git
+ * repository. Cheaper than `collectUncommitted`: it reads no file contents.
+ */
+export async function listDirtyPaths(
+    exec: ExecFn,
+    cwd: string,
+): Promise<Set<string> | undefined> {
+    return (await collectChangedPaths(exec, cwd))?.paths;
+}
+
+/**
+ * Read every uncommitted change in `cwd`: staged and unstaged tracked edits,
+ * plus untracked files. Uses `--no-renames` so renames arrive as a delete plus
+ * an add, which keeps content diffing simple.
+ */
+export async function collectUncommitted(
+    exec: ExecFn,
+    cwd: string,
+): Promise<DiffFile[]> {
+    const changed = await collectChangedPaths(exec, cwd);
+    if (!changed) {
+        throw new Error('not a git repository');
+    }
+    const { hasHead, paths } = changed;
+
+    const files: DiffFile[] = [];
+    for (const path of [...paths].sort()) {
+        const head = hasHead ? await readHead(exec, cwd, path) : undefined;
+        const work = await readWorktree(resolve(cwd, path));
+
+        if (work.kind === 'unreadable') {
+            files.push({ path, status: 'unreadable', diff: '' });
+            continue;
+        }
+        if (
+            work.kind === 'binary' ||
+            (head !== undefined && looksBinary(head))
+        ) {
+            files.push({ path, status: 'binary', diff: '' });
+            continue;
+        }
+        if (work.kind === 'too-large') {
+            files.push({ path, status: 'too-large', diff: '' });
+            continue;
+        }
+
+        const before = head ?? '';
+        const after = work.kind === 'text' ? work.text : '';
+        const status: FileStatus =
+            head === undefined
+                ? 'added'
+                : work.kind === 'missing'
+                  ? 'deleted'
+                  : 'modified';
+
+        const { diff } = generateDiffString(before, after);
+        if (!diff && status === 'modified') continue; // mode-only change, nothing to show
+        files.push({ path, status, diff: capLines(diff) });
+    }
+
+    return files;
+}