@gavin-hu/my-pi-agent 0.12.0 → 0.13.1

package/extensions/plan/web.ts

@@ -25,7 +25,8 @@ import {
 	type PlanAnnotation,
 } from "./feedback.ts";
 import { planTitle, type PlanStore, type StoredPlan } from "./plans.ts";
-import { changedSections, extractPlanSections, extractPlanSteps } from "./steps.ts";
+import { changedSections, type SectionDigest } from "./plan-text.ts";
+import { extractPlanSections, extractPlanSteps } from "./steps.ts";
 import {
 	handleReviewRequest,
 	JSON_HEADERS,
@@ -59,8 +60,8 @@ export interface PlanReviewOptions {
 	signal?: AbortSignal;
 	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
 	canApprove?: boolean;
-	/** The content the previous review showed, so this page can mark changed sections. */
-	previous?: string;
+	/** The section digests the previous review showed, so this page can mark changed sections. */
+	baseline?: SectionDigest[];
 }
 
 /** Starts and tracks review sessions. */
@@ -166,31 +167,31 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 
 		// The stripped plan the page last rendered; a save must anchor against a file
 		// that still matches it, or the comments land beside the wrong text.
-		let baseline = stripFeedback(plan.content);
+		let pageText = stripFeedback(plan.content);
 		let savedPlan: StoredPlan | undefined;
 		// Set by `onSaved`/`onCancel`; resolved once the HTTP response has flushed,
 		// so the caller cannot close the socket before the browser sees the reply.
 		let pendingResult: PlanReviewResult | undefined;
 
 		/**
-		 * Re-read the plan into `baseline` and return it. Named apart from the page
+		 * Re-read the plan into `pageText` and return it. Named apart from the page
 		 * build because it writes the state a later save validates against, so a `GET`
 		 * does not hide that write inside what looks like a read.
 		 */
-		const refreshBaseline = async (): Promise<StoredPlan> => {
+		const refreshPageText = async (): Promise<StoredPlan> => {
 			const current = (await store.read(cwd, plan.path)) ?? plan;
-			baseline = stripFeedback(current.content);
+			pageText = stripFeedback(current.content);
 			return current;
 		};
 
 		const page = async (): Promise<ReviewPageData> => {
-			const stored = await refreshBaseline();
-			const current = baseline;
+			const stored = await refreshPageText();
+			const current = pageText;
 			const blocks = planBlocks(current);
 			const sections = extractPlanSections(current);
 			// Per-occurrence change flags, aligned with the sections list: the same shape
 			// the terminal review renders, so duplicate headings cannot both light up.
-			const changed = options.previous === undefined ? [] : changedSections(stripFeedback(options.previous), current);
+			const changed = changedSections(options.baseline, current);
 			const outline = sections.flatMap((section, index) =>
 				section.title === ""
 					? []
@@ -236,7 +237,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 		const save = async (annotations: PlanAnnotation[]): Promise<SaveResult> => {
 			const current = await store.read(cwd, plan.path);
 			if (!current) return { ok: false, status: 404, message: "The plan file is gone." };
-			if (stripFeedback(current.content) !== baseline) {
+			if (stripFeedback(current.content) !== pageText) {
 				return { ok: false, status: 409, message: "The plan changed on disk; reload the page and review again." };
 			}
 			try {

package/extensions/rewind/README.md

@@ -28,6 +28,12 @@ pi install ./                        # install the package
   **Conversation only**, or **Code only**.
   - *Code* rewrites the working tree to the snapshot and is itself undoable
     (a `pre-restore` safety snapshot is taken first).
+  - When code moves, a second step asks **Restore what?** — **Everything (N
+    files)** or **Choose paths…**. The checklist lists every changed path
+    grouped by directory (`M` modified, `D` deleted since the snapshot, `A`
+    created after it), with all of them selected, so `Enter` twice reproduces a
+    whole-tree restore. `Space` toggles a file or a directory, `a`/`n` select
+    all/none, and the confirm that follows previews only the chosen subset.
   - *Conversation* moves the session tree back to that prompt and puts the
     prompt text back in the editor; the abandoned branch stays in the session.
 - Shows a `↺ N` status chip counting the prompts on the active branch — the
@@ -45,18 +51,23 @@ the main checkout; `list`/matching filter to the current root by default.
 
 | Command | What it does |
 |---|---|
-| `/rewind` | Open the timeline; pick a prompt, then a restore scope. |
+| `/rewind` | Open the timeline; pick a prompt, then a restore scope, then (for code) the paths. |
+
+The path checklist is its own `ctx.ui.custom` screen: `Space` toggles the focused
+row, `a`/`n` select all or none, `Enter` returns the selection, and `Esc` cancels
+the rewind.
 
 The timeline is keyboard-driven: `↑`/`↓` or `j`/`k` move, `PgUp`/`PgDn`/`Home`/`End`
 jump, `Enter` chooses the focused prompt, the mouse wheel scrolls, `Esc` closes.
 The scope choice and the confirmation (with a diff preview) run after the screen
-closes.
+closes. The path checklist is the same grammar: `Space` toggles, `a`/`n` select
+all or none, `Enter` restores the selection, `Esc` cancels the rewind.
 
 ## Behaviour by mode
 
 | Mode | Behaviour |
 |---|---|
-| Interactive TUI | Full selectable timeline component; scope choice and confirmation follow after it closes. |
+| Interactive TUI | Full selectable timeline component, then the scope choice, the path checklist, and the confirmation. |
 | RPC (`hasUI`) | Timeline falls back to `ui.select`; scope choice and confirmation use forwarded dialogs. |
 | `print` / `json` | No picker: the prompt list is printed. |
 
@@ -110,9 +121,14 @@ A clean working tree still records a commit (so the metadata always travels with
 the snapshot); git reuses the identical tree object, so the only cost is a small
 commit. These refs are not branches and are not touched by `git push --all`.
 
+## Limitations
+
+- **The path checklist is TUI-only.** RPC, `print`, and `json` modes restore the
+  whole tree; there is no typed path syntax, because a list of exact paths is what
+  the checklist is for and a glob would need its own validation and preview.
+
 ## Non-goals
 
-- No per-file or partial code rewind; a restore is all-or-nothing.
 - No capture of `.gitignore`d files.
 - No moving HEAD, committing, stashing, or pushing.
 - No non-git projects for code snapshots (conversation-only rewind still works
@@ -126,7 +142,7 @@ commit. These refs are not branches and are not touched by `git push --all`.
 |---|---|
 | Model-facing tools | None. `/rewind` is user-driven; automatic snapshots cover the start of every task. |
 | Commands | `/rewind` (`pi.registerCommand`). |
-| Events | `session_start` (reset run state, status, stale-index sweep), `session_tree` (status refresh after tree navigation), `before_agent_start` (capture the prompt and resolve the run's snapshot decision), `tool_call` (take the run's snapshot before the first mutating call), `session_shutdown` (release indexes, clear status). |
+| Events | `session_start` (reset run state, status, stale-index sweep), `session_tree` (status refresh after tree navigation), `before_agent_start` (record the prompt — absent on a run a custom message starts — and resolve the run's snapshot decision), `tool_call` (take the run's snapshot before the first mutating call), `session_shutdown` (release indexes, clear status). |
 | State storage | Git refs `refs/pi/rewind/<id>` with metadata in the commit body. No tool-result `details` and no `pi.appendEntry`. |
 | Lifecycle | Index paths are created lazily and released in `session_shutdown`; status chip is set on start/tree/snapshot and cleared on shutdown. |
 
@@ -136,7 +152,9 @@ commit. These refs are not branches and are not touched by `git push --all`.
   `before_agent_start` records the prompt summary and resolves the run's root,
   policy, and config, so the first mutating `tool_call` takes the snapshot with a
   fully synchronous guard. No `await` sits between that guard's check and its
-  claim, so parallel sibling calls cannot double-snapshot.
+  claim, so parallel sibling calls cannot double-snapshot. A run a custom message
+  starts (a wake) has no prompt to record; the snapshot it takes is otherwise the
+  same.
 - **The timeline comes from the session tree, not from git.** `/rewind` lists
   every user message on the active branch and pairs each with the snapshot whose
   recorded `entryId` matches, so read-only prompts appear too and the list
@@ -190,7 +208,9 @@ commit. These refs are not branches and are not touched by `git push --all`.
 | `git.ts` | Single git entry point: rewind plumbing, the shared read helpers rewind consumes, and the production `RunGit`. |
 | `snapshot.ts` | Create a snapshot (tree from a temporary index → commit → ref). |
 | `snapshot-run.ts` | Per-run automatic-snapshot state: one snapshot per prompt, with a synchronous guard. |
-| `restore.ts` | Plan and apply a working-tree rewind. |
+| `restore.ts` | Plan and apply a working-tree rewind, whole or for a chosen subset of paths. |
+| `paths.ts` | Pure: the changed-path list from `git diff --name-status`, its directory grouping, the change marks, and the restore counts. |
+| `path-picker.ts` | The checklist screen a partial restore opens: grouped paths, toggles, and the selection it returns. |
 | `store.ts` | Versioned metadata encoding and ref-backed listing/pruning. |
 | `policy.ts` | Which tool calls are worth a snapshot. |
 | `temp-index.ts` | Per-process `GIT_INDEX_FILE` paths: create, release, and sweep stale files. |
@@ -198,7 +218,7 @@ commit. These refs are not branches and are not touched by `git push --all`.
 | `queue.ts` | The serialized git operation queue for staging calls (`GIT_INDEX_FILE`). |
 | `runtime.ts` | Root/config caches and the snapshot/list/plan/restore operations. |
 | `timeline.ts` | Pure: prompts on the branch, paired with their snapshots. |
-| `rewind.ts` | Scope choice, confirmation, and applying code + conversation rewind. |
+| `rewind.ts` | Scope choice, the path step, confirmation, and applying code + conversation rewind. |
 | `rewind-tui.ts` | The selectable, width-safe timeline component, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `commands.ts` | The `/rewind` command. |
 | `format.ts` | Model-facing and transcript text (pure). |

package/extensions/rewind/commands.ts

@@ -61,7 +61,7 @@ async function openRewind(pi: ExtensionAPI, runtime: RewindRuntime, ctx: Extensi
 
 	const point = await withRailsSuppressed(pi, () => choosePoint(ctx, points));
 	if (!point) return;
-	await rewindTo(runtime, ctx, root, point);
+	await rewindTo(pi, runtime, ctx, root, point);
 }
 
 export function registerCommands(pi: ExtensionAPI, runtime: RewindRuntime): void {

package/extensions/rewind/format.ts

@@ -131,11 +131,11 @@ export function previewDiffText(diff: string, maxLines = DIFF_PREVIEW_LINES): st
 	return [...lines.slice(0, maxLines), `… ${lines.length - maxLines} more lines`].join("\n");
 }
 
-/** Restore confirmation text. */
+/** Restore confirmation text; a partial restore also names how much it covered. */
 export function formatRestoreText(summary: RestoreSummary): string {
-	const parts = [
-		`Restored snapshot #${summary.id}: ${summary.changed} file${summary.changed === 1 ? "" : "s"} changed`,
-	];
+	const scope = summary.of === undefined ? "" : ` of ${summary.of}`;
+	const files = `${summary.changed}${scope} file${summary.changed === 1 && summary.of === undefined ? "" : "s"}`;
+	const parts = [`Restored snapshot #${summary.id}: ${files} changed`];
 	if (summary.removed > 0) parts.push(`${summary.removed} removed`);
 	const line = `${parts.join(", ")}.`;
 	const safety = summary.safety ? ` A safety snapshot #${summary.safety} captures the pre-restore state.` : "";

package/extensions/rewind/git.ts

@@ -22,6 +22,7 @@ import {
 	runGitOrThrow as run,
 	type RunGit,
 } from "../../lib/git/index.ts";
+import { parseNameStatus, type ChangedPath } from "./paths.ts";
 
 // Re-export exactly the shared helpers this extension consumes, so rewind code
 // has one git import surface instead of reaching into `lib/git` directly.
@@ -128,33 +129,70 @@ export async function readTreeReset(runGit: RunGit, cwd: string, commit: string,
 	await run(runGit, ["read-tree", "--reset", "-u", commit], { cwd, env: { GIT_INDEX_FILE: indexFile } });
 }
 
-/** Paths added between two trees (present in `to`, absent from `from`). */
-export async function addedPaths(runGit: RunGit, cwd: string, from: string, to: string): Promise<string[]> {
-	const result = await runGit(["diff", "--no-color", "--name-only", "--diff-filter=A", from, to], { cwd });
-	if (result.code !== 0) return [];
-	return result.stdout.split("\n").filter((line) => line.trim().length > 0);
+/**
+ * A pathspec that matches `path` literally.
+ *
+ * The paths come from `git diff` output, so a file named `weird[1].txt` is a real
+ * possibility; without `:(literal)` git would read it as a glob and restore the
+ * wrong thing (or nothing).
+ */
+function literalPathspec(path: string): string {
+	return `:(literal)${path}`;
 }
 
-/** `git diff --stat` between two trees. */
-export async function diffStat(runGit: RunGit, cwd: string, from: string, to: string): Promise<string> {
-	const result = await runGit(["diff", "--no-color", "--stat", from, to, "--"], { cwd });
-	return result.code === 0 ? result.stdout.trim() : "";
+/**
+ * The changed paths between two trees, with how each changed.
+ *
+ * One call replaces the separate added-path and changed-count queries, so the
+ * preview, the checklist, and the apply step all read the same list.
+ */
+export async function nameStatus(
+	runGit: RunGit,
+	cwd: string,
+	from: string,
+	to: string,
+	paths?: readonly string[],
+): Promise<ChangedPath[]> {
+	const args = ["diff", "--no-color", "--name-status", from, to, "--"];
+	if (paths) args.push(...paths.map(literalPathspec));
+	const result = await runGit(args, { cwd });
+	return result.code === 0 ? parseNameStatus(result.stdout) : [];
 }
 
-/** Count of paths changed between two trees, optionally filtered by diff status. */
-export async function changedCount(
+/** `git diff --stat` between two trees, optionally limited to `paths`. */
+export async function diffStat(
 	runGit: RunGit,
 	cwd: string,
 	from: string,
 	to: string,
-	filter?: string,
-): Promise<number> {
-	const args = ["diff", "--no-color", "--name-only"];
-	if (filter) args.push(`--diff-filter=${filter}`);
-	args.push(from, to, "--");
+	paths?: readonly string[],
+): Promise<string> {
+	const args = ["diff", "--no-color", "--stat", from, to, "--"];
+	if (paths) args.push(...paths.map(literalPathspec));
 	const result = await runGit(args, { cwd });
-	if (result.code !== 0) return 0;
-	return result.stdout.split("\n").filter((line) => line.trim().length > 0).length;
+	return result.code === 0 ? result.stdout.trim() : "";
+}
+
+/**
+ * Rewrite the given paths in the working tree from `commit`.
+ *
+ * `read-tree --reset -u` takes no pathspec, so a partial restore checks the paths
+ * out of the snapshot instead. The index it writes is the temporary one, so the
+ * real index stays untouched exactly as the whole-tree reset leaves it. Callers
+ * pass only paths present in `commit`; an added path is deleted, not checked out.
+ */
+export async function restorePaths(
+	runGit: RunGit,
+	cwd: string,
+	commit: string,
+	indexFile: string,
+	paths: readonly string[],
+): Promise<void> {
+	if (paths.length === 0) return;
+	await run(runGit, ["checkout", commit, "--", ...paths.map(literalPathspec)], {
+		cwd,
+		env: { GIT_INDEX_FILE: indexFile },
+	});
 }
 
 /** Label of an in-progress git operation that a rewind must not clobber, if any. */

package/extensions/rewind/index.ts

@@ -36,12 +36,10 @@ export function registerRewind(pi: ExtensionAPI): void {
 		await runtime.setStatus(ctx);
 	});
 
-	// A new prompt begins a task: the run resolves its snapshot decision up
-	// front, so the `tool_call` guard can stay synchronous. A run started by a
-	// custom message (a wake) has no user prompt — `event.prompt` is undefined
-	// there despite its type — so `beginRun` accepts a missing prompt.
+	// A run started by a custom message (a wake) has no user prompt: only a user
+	// run carries one, and a newer host spells that as a union on `messageType`.
 	pi.on("before_agent_start", async (event, ctx) => {
-		await run.beginRun(event.prompt, ctx);
+		await run.beginRun("prompt" in event ? event.prompt : undefined, ctx);
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {

package/extensions/rewind/path-picker.ts

@@ -0,0 +1,198 @@
+/**
+ * The path checklist a partial rewind opens: every changed path, grouped by
+ * directory, each one togglable.
+ *
+ * The screen is the timeline's sibling — same dock frame, same cursor, same
+ * width-safe row grammar — so a partial restore reads as one more step in
+ * `/rewind` rather than a second product. Rows are selected by default, which
+ * makes `Enter` here reproduce the whole-tree restore exactly.
+ *
+ * The component owns only the selection: paths in, a chosen subset out through
+ * `onClose`, and the restore itself stays behind the confirmation that follows.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
+import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { checkbox, listRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { baseName, expandGroup, groupPaths, SELECTION_MARKS, type ChangedPath, type PathGroup } from "./paths.ts";
+
+export interface PathPickerOptions {
+	/** The changed paths the snapshot differs on. */
+	paths: readonly ChangedPath[];
+	theme: Theme;
+	/** Called once when the screen closes: the selected paths, or undefined when cancelled. */
+	onClose: (paths?: string[]) => void;
+	requestRender: () => void;
+	viewportRows?: ViewportRowsSource;
+}
+
+/** Rows the screen shows when the terminal height is unknown. */
+const SCREEN_DEFAULT_ITEMS = 12;
+/** Header, summary, blanks, and footer rows around the list. */
+const SCREEN_CHROME_ROWS = 6;
+
+/** One rendered row: a directory header or a file under one. */
+type Row = { kind: "group"; group: PathGroup } | { kind: "file"; path: ChangedPath; dir: string };
+
+/** The checklist of changed paths. */
+export class PathPickerComponent implements Component {
+	private readonly cursor: ListCursor;
+	private readonly groups: PathGroup[];
+	private readonly rows: Row[];
+	private readonly chosen = new Set<string>();
+
+	constructor(private readonly options: PathPickerOptions) {
+		this.cursor = new ListCursor(options.requestRender);
+		this.groups = groupPaths(options.paths);
+		// Every path starts selected, so confirming without touching anything means
+		// "restore it all" — the behavior `/rewind` had before the checklist existed.
+		for (const group of this.groups) for (const path of expandGroup(group)) this.chosen.add(path);
+		this.rows = this.groups.flatMap((group): Row[] => [
+			{ kind: "group", group },
+			...group.paths.map((path): Row => ({ kind: "file", path, dir: group.dir })),
+		]);
+	}
+
+	/** Whether every file under `group` is selected. */
+	private groupOn(group: PathGroup): boolean {
+		return group.paths.every((path) => this.chosen.has(path.path));
+	}
+
+	/** Toggle every file under `group` to `on`. */
+	private setGroup(group: PathGroup, on: boolean): void {
+		for (const path of expandGroup(group)) {
+			if (on) this.chosen.add(path);
+			else this.chosen.delete(path);
+		}
+	}
+
+	/** Apply a key press. Exposed for the tests that drive the screen directly. */
+	handleInput(data: string): void {
+		if (isCloseKey(data)) {
+			this.options.onClose(undefined);
+			return;
+		}
+		if (navigateList(data, this.cursor, this.rows.length)) return;
+		if (data === " ") {
+			const row = this.rows[this.cursor.selected];
+			if (row?.kind === "group") this.setGroup(row.group, !this.groupOn(row.group));
+			else if (row) {
+				if (this.chosen.has(row.path.path)) this.chosen.delete(row.path.path);
+				else this.chosen.add(row.path.path);
+			}
+			this.options.requestRender();
+			return;
+		}
+		if (data === "a") {
+			for (const path of this.options.paths) this.chosen.add(path.path);
+			this.options.requestRender();
+			return;
+		}
+		if (data === "n") {
+			this.chosen.clear();
+			this.options.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.enter)) this.options.onClose([...this.chosen]);
+	}
+
+	/** Wheel scrolling in fullscreen moves the cursor; regular mode leaves the wheel to the terminal. */
+	handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		return scrollList(event, this.cursor, this.rows.length);
+	}
+
+	dispose(): void {}
+
+	invalidate(): void {}
+
+	// The shared dock frame, like every other list screen.
+	render(width: number): string[] {
+		const w = Math.max(1, width);
+		const header = titleRule(this.theme, w, "Restore paths");
+		const cursor = this.cursor;
+		cursor.visible = fitRows(this.options.viewportRows, this.rows.length, SCREEN_CHROME_ROWS, SCREEN_DEFAULT_ITEMS);
+		const { start, end } = cursor.window(this.rows.length);
+
+		const body: string[] = [];
+		for (let i = start; i < end; i++) body.push(this.rowLine(w, this.rows[i], i === cursor.selected));
+
+		const total = this.options.paths.length;
+		const selected = this.chosen.size;
+		return dockListFrame({
+			header,
+			summary: clip(
+				`  ${paint(this.theme, "meta", `${selected} of ${total} selected${SEPARATORS.item}Space toggles a file or a directory`)}`,
+				w,
+			),
+			body,
+			range: cursor.clipped(this.rows.length)
+				? formatRange(this.theme, w, { start, end, total: this.rows.length })
+				: undefined,
+			detail: this.detail(w),
+			hint: this.hint(w),
+		});
+	}
+
+	private get theme(): Theme {
+		return this.options.theme;
+	}
+
+	/** One row: a directory header with its count, or a file with its change mark. */
+	private rowLine(width: number, row: Row, selected: boolean): string {
+		const tone = selected ? "accent" : row.kind === "group" ? "meta" : "label";
+		if (row.kind === "group") {
+			const count = row.group.paths.length;
+			return listRow(this.theme, width, {
+				selected,
+				leading: checkbox(this.theme, this.groupOn(row.group)),
+				label: `${row.group.dir === "" ? "./" : `${row.group.dir}/`}`,
+				labelRole: tone,
+				trailing: `${count} file${count === 1 ? "" : "s"}`,
+				trailingRole: "meta",
+			});
+		}
+		return listRow(this.theme, width, {
+			selected,
+			indent: 2,
+			// The header already carries the directory's checkbox, so the file rows
+			// keep the column with a blank rather than repeating it.
+			leading: " ",
+			label: baseName(row.path.path),
+			labelRole: tone,
+			trailing: SELECTION_MARKS[row.path.change],
+			trailingRole: row.path.change === "added" ? "warn" : "meta",
+		});
+	}
+
+	/** What the focused row will do, in words. */
+	private detail(width: number): string[] | undefined {
+		const row = this.rows[this.cursor.selected];
+		if (!row) return undefined;
+		const text =
+			row.kind === "group"
+				? `Space selects or clears all ${row.group.paths.length} file${row.group.paths.length === 1 ? "" : "s"} in this directory.`
+				: row.path.change === "added"
+					? "A — created after the snapshot; restoring removes it."
+					: row.path.change === "deleted"
+						? "D — deleted since the snapshot; restoring brings it back."
+						: "M — modified since the snapshot; restoring rewrites it.";
+		return [clip(`  ${paint(this.theme, "meta", text)}`, width)];
+	}
+
+	/** The key-hint row, with the primary action in the accent role. */
+	private hint(width: number): string {
+		return screenHint(this.theme, width, [
+			"Esc cancel",
+			{ text: "Enter restore", color: "accent" },
+			"Space toggle",
+			"a all",
+			"n none",
+		]);
+	}
+}

package/extensions/rewind/paths.ts

@@ -0,0 +1,128 @@
+/**
+ * The changed paths a rewind can restore, and how the picker groups them.
+ *
+ * `git diff --name-status <snapshot> <working tree>` is the one source of truth:
+ * the preview, the checklist, and the apply step all read this list, so they
+ * cannot disagree about what changed. Pure: parsing, grouping, marks, and the
+ * counts `RestoreSummary` reports.
+ *
+ * A rename arrives as `R100\told\tnew`. It is expanded into two entries — the old
+ * path as deleted and the new one as added — because that is exactly what the
+ * restore does to each: selecting the old path brings it back, selecting the new
+ * one removes it. Both rows appear in the checklist rather than one opaque one.
+ */
+
+/** What a restore does to one path. */
+export type PathChange = "modified" | "deleted" | "added";
+
+/** One path the snapshot differs on, and how. */
+export interface ChangedPath {
+	/** Repository-relative path, as git reports it. */
+	path: string;
+	change: PathChange;
+}
+
+/** The trailing mark for each change in the checklist. */
+export const SELECTION_MARKS: Readonly<Record<PathChange, string>> = {
+	modified: "M",
+	deleted: "D",
+	added: "A",
+};
+
+/** One directory's files, for the checklist's grouping. */
+export interface PathGroup {
+	/** Directory relative to the root; `""` for files at the root. */
+	dir: string;
+	/** The group's files, sorted by path. */
+	paths: ChangedPath[];
+}
+
+/** The status letter → change kind, for the single-path statuses. */
+function changeOf(letter: string): PathChange | undefined {
+	switch (letter) {
+		case "M":
+		case "T": // a type change (file ↔ symlink) rewrites the path
+			return "modified";
+		case "D":
+			return "deleted";
+		case "A":
+			return "added";
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Parse `git diff --name-status` output. A rename expands to both of its paths
+ * (as described in the module comment) and a copy to its destination only — the
+ * source is untouched, so it is not a changed path. An unknown status letter is
+ * skipped rather than guessed at.
+ */
+export function parseNameStatus(stdout: string): ChangedPath[] {
+	const changed: ChangedPath[] = [];
+	for (const line of stdout.split("\n")) {
+		if (line.trim() === "") continue;
+		const [status, first, second] = line.split("\t");
+		if (!status || !first) continue;
+		const letter = status[0] ?? "";
+		if (letter === "R" || letter === "C") {
+			if (!second) continue;
+			if (letter === "R") changed.push({ path: first, change: "deleted" });
+			changed.push({ path: second, change: "added" });
+			continue;
+		}
+		const kind = changeOf(letter);
+		if (kind) changed.push({ path: first, change: kind });
+	}
+	return changed;
+}
+
+/** The directory part of a path, or `""` for the root. */
+function dirOf(path: string): string {
+	const slash = path.lastIndexOf("/");
+	return slash === -1 ? "" : path.slice(0, slash);
+}
+
+/** The file name within its directory. */
+export function baseName(path: string): string {
+	const slash = path.lastIndexOf("/");
+	return slash === -1 ? path : path.slice(slash + 1);
+}
+
+/**
+ * Group changed paths by directory: the root first, then directories in
+ * lexicographic order, files sorted inside each group. A stable order is what
+ * makes the checklist's cursor predictable and the golden renders testable.
+ */
+export function groupPaths(paths: readonly ChangedPath[]): PathGroup[] {
+	const groups = new Map<string, ChangedPath[]>();
+	for (const entry of paths) {
+		const dir = dirOf(entry.path);
+		const group = groups.get(dir);
+		if (group) group.push(entry);
+		else groups.set(dir, [entry]);
+	}
+	return [...groups.entries()]
+		.map(([dir, entries]) => ({ dir, paths: [...entries].sort((a, b) => a.path.localeCompare(b.path)) }))
+		.sort((a, b) => (a.dir === "" ? -1 : b.dir === "" ? 1 : a.dir.localeCompare(b.dir)));
+}
+
+/** The paths a directory toggle selects. */
+export function expandGroup(group: PathGroup): string[] {
+	return group.paths.map((entry) => entry.path);
+}
+
+/**
+ * The counts the plan and the summary report: `changed` is modified plus deleted
+ * (files rewritten from the snapshot), and `removed` is the paths created after
+ * it, which the restore deletes.
+ */
+export function summarize(paths: readonly ChangedPath[]): { changed: number; removed: number } {
+	let changed = 0;
+	let removed = 0;
+	for (const entry of paths) {
+		if (entry.change === "added") removed++;
+		else changed++;
+	}
+	return { changed, removed };
+}