@young1lin/dsh-ui-gitworkbench 0.1.3 → 0.1.5

package/src/client/locales.ts

@@ -20,11 +20,17 @@
 /** Every key this plugin looks up — the two dictionaries below must both cover it. */
 export type WorkbenchKey =
   | 'aheadTitle' | 'behindTitle' | 'files'
+  | 'filterFiles' | 'filterFilesPlaceholder' | 'filterFilesClear' | 'filesFiltered' | 'filterNoMatch'
   | 'drawerLabel' | 'totalsDim' | 'refresh' | 'close'
   | 'tabsLabel' | 'tabChanges' | 'tabHistory' | 'tabCompare'
   | 'sourceLabel' | 'workingTree'
   | 'loadingCommit' | 'renamedFrom' | 'binaryFile' | 'loadingDiff' | 'noTextDiff'
   | 'noCommits' | 'historyLabel' | 'historyEnd' | 'loading' | 'maximize' | 'restore'
+  | 'commitAuthor' | 'commitCommitter' | 'commitDate' | 'historyFilterPlaceholder' | 'historyNoMatch'
+  | 'filterClearAll' | 'filterBy' | 'filterUsers' | 'filterUserSearch' | 'filterAuthorsMore'
+  | 'filterDate' | 'filterToday' | 'filterLast7' | 'filterLast30' | 'filterAfter' | 'filterBefore'
+  | 'filterPaths' | 'filterPathsMore' | 'allBranches' | 'filterPathSearch'
+  | 'filterCalendarSets' | 'filterSelected' | 'filterLocale'
   | 'compareBase' | 'compareHead' | 'comparePick' | 'compareCommits' | 'loadingCompare' | 'noBranches'
   | 'refSearch' | 'refNone' | 'refCount' | 'refTruncated' | 'refWorktrees' | 'refBranches' | 'historyRefLabel'
   | 'settings' | 'themeMode' | 'themePalette' | 'themeScope' | 'themeBackground' | 'themeCss'
@@ -42,6 +48,9 @@ export type WorkbenchKey =
   | 'stage' | 'unstage' | 'stageAll' | 'unstageAll' | 'stagedCount'
   | 'commit' | 'amend' | 'commitPlaceholder' | 'commitNeedMessage' | 'commitLead'
   | 'op.ok.stage' | 'op.ok.unstage' | 'op.ok.commit' | 'op.ok.fetch' | 'op.ok.pull' | 'op.ok.push'
+  | 'op.ok.discardFile'
+  | 'discardAction' | 'discardTitle' | 'discardConfirm' | 'discardCancel'
+  | 'discardBodyRestore' | 'discardBodyDelete' | 'discardBodyUnrename'
   | 'op.fail.auth' | 'op.fail.network' | 'op.fail.no-upstream' | 'op.fail.diverged' | 'op.fail.conflict'
   | 'op.fail.nothing-to-commit' | 'op.fail.dirty' | 'op.fail.unknown'
 
@@ -112,8 +121,44 @@ export const zh: Record<WorkbenchKey, string> = {
   noTextDiff: '无文本差异',
   noCommits: '无提交历史',
   historyLabel: '提交历史',
+  commitAuthor: '作者',
+  commitCommitter: '提交者',
+  commitDate: '提交时间',
+  historyFilterPlaceholder: '筛选：user: 名字 / path: 路径 / after: 日期 / 关键词',
+  historyNoMatch: '没有匹配的提交',
+  filterClearAll: '清除全部',
+  filterBy: '筛选条件',
+  filterUsers: '用户',
+  filterUserSearch: '搜索作者',
+  filterAuthorsMore: '仅显示提交最多的 500 位作者',
+  filterDate: '日期',
+  filterToday: '今天',
+  filterLast7: '最近 7 天',
+  filterLast30: '最近 30 天',
+  filterAfter: '之后',
+  filterBefore: '之前',
+  filterPaths: '路径',
+  filterPathsMore: '文件过多，目录树已截断',
+  filterPathSearch: '搜索文件或目录',
+  filterCalendarSets: '日历写入',
+  filterSelected: '已选 {count} 项',
+  // BCP-47 tag for the filter calendar. The month title and the weekday row
+  // used to come from `Intl.DateTimeFormat(undefined, …)`, i.e. the BROWSER's
+  // language — an English drawer on a zh-CN machine printed "2026年8月" over
+  // 一二三四五六日. The dictionary is what knows which language the drawer is
+  // speaking, so the tag lives here.
+  filterLocale: 'zh-CN',
+  allBranches: '全部分支',
   expandAll: '展开全部',
   collapseAll: '收起全部',
+  // Filtering the file list. Separate from the funnel above the commit list:
+  // that one asks git for a different set of commits, this one only hides rows
+  // already on screen.
+  filterFiles: '过滤文件',
+  filterFilesPlaceholder: '过滤文件，空格分隔多个关键字',
+  filterFilesClear: '清除过滤',
+  filesFiltered: '{shown} / {count} 文件',
+  filterNoMatch: '没有匹配的文件',
   noBranch: '(无分支)',
   copyCommit: '复制提交说明',
   copiedCommit: '已复制',
@@ -147,6 +192,19 @@ export const zh: Record<WorkbenchKey, string> = {
   'op.ok.fetch': '已获取远端信息',
   'op.ok.pull': '拉取完成',
   'op.ok.push': '推送成功',
+  'op.ok.discardFile': '已撤回',
+  // The row action, and the dialog it opens. IDEA calls this Rollback and
+  // means "take the file back to its committed state" — not "undo my last
+  // edit", which is the editor's job and a different promise.
+  discardAction: '撤回改动',
+  discardTitle: '撤回改动？',
+  discardConfirm: '撤回',
+  discardCancel: '取消',
+  // One body per consequence. The dialog never says a generic "are you sure":
+  // the whole point of it is to name which of these three is about to happen.
+  discardBodyRestore: '{path} 将还原成上次提交时的样子。这里的 {added} 行新增、{deleted} 行删除无法找回。',
+  discardBodyDelete: '{path} 从未被 git 记录过，删除后无法找回。',
+  discardBodyUnrename: '撤销重命名：{path} 改回 {previousPath}，改名期间的内容改动一并丢弃。',
   'op.fail.auth': '认证失败。凭据提示已被禁用，请先在终端里配置好凭据再重试。',
   'op.fail.network': '网络不可达：主机名解析失败或连接不上。检查网络与远程地址后重试。',
   'op.fail.no-upstream': '当前分支没有上游分支。',
@@ -224,8 +282,36 @@ export const en: Record<WorkbenchKey, string> = {
   noTextDiff: 'No text changes',
   noCommits: 'No commit history',
   historyLabel: 'Commit history',
+  commitAuthor: 'Author',
+  commitCommitter: 'Committer',
+  commitDate: 'Committed',
+  historyFilterPlaceholder: 'Filter: user: name / path: dir / after: date / text',
+  historyNoMatch: 'No matching commits',
+  filterClearAll: 'Clear all',
+  filterBy: 'Filter by',
+  filterUsers: 'Users',
+  filterUserSearch: 'Search authors',
+  filterAuthorsMore: 'Showing the 500 busiest authors only',
+  filterDate: 'Date',
+  filterToday: 'Today',
+  filterLast7: 'Last 7 days',
+  filterLast30: 'Last 30 days',
+  filterAfter: 'After',
+  filterBefore: 'Before',
+  filterPaths: 'Paths',
+  filterPathsMore: 'Too many files — tree truncated',
+  filterPathSearch: 'Search files or folders',
+  filterCalendarSets: 'Calendar sets',
+  filterSelected: '{count} selected',
+  filterLocale: 'en-US',
+  allBranches: 'All branches',
   expandAll: 'Expand all',
   collapseAll: 'Collapse all',
+  filterFiles: 'Filter files',
+  filterFilesPlaceholder: 'Filter files; space-separated terms',
+  filterFilesClear: 'Clear filter',
+  filesFiltered: '{shown} / {count} files',
+  filterNoMatch: 'No file matches',
   noBranch: '(no branch)',
   copyCommit: 'Copy message',
   copiedCommit: 'Copied',
@@ -259,6 +345,14 @@ export const en: Record<WorkbenchKey, string> = {
   'op.ok.fetch': 'Fetched',
   'op.ok.pull': 'Pulled',
   'op.ok.push': 'Pushed',
+  'op.ok.discardFile': 'Rolled back',
+  discardAction: 'Roll back changes',
+  discardTitle: 'Roll back changes?',
+  discardConfirm: 'Roll back',
+  discardCancel: 'Cancel',
+  discardBodyRestore: '{path} goes back to its committed content. The {added} added and {deleted} deleted lines here cannot be recovered.',
+  discardBodyDelete: '{path} was never recorded by git. Deleting it cannot be undone.',
+  discardBodyUnrename: 'Undo the rename: {path} goes back to {previousPath}, and content changed along the way is lost.',
   'op.fail.auth': 'Authentication failed. Credential prompts are disabled here — set your credentials up in a terminal first.',
   'op.fail.network': 'The network was unreachable — the host could not be resolved or the connection failed. Check connectivity and the remote URL, then retry.',
   'op.fail.no-upstream': 'This branch has no upstream.',

package/src/client/log-filter-query.ts

@@ -0,0 +1,189 @@
+/**
+ * The query-box grammar for the history filter, and its chip model.
+ *
+ * The box and the funnel popup are two views of ONE LogFilter: typing
+ * `user:lia after:2 weeks ago` and ticking authors in the popup produce the
+ * same object, rendered back into the box by {@link serializeLogQuery} and
+ * into removable chips by {@link chipsFromFilter}. Everything is pure so the
+ * grammar round-trips under test: parse(serialize(f)) === f.
+ *
+ * Grammar (prefixes case-insensitive, IDEA-style):
+ *   bare words      → the text criterion (commit-message match)
+ *   user:<name>     → author; repeatable, multiple OR
+ *   path:<spec>     → pathspec; repeatable, union
+ *   after:<date>    → approxidate lower bound, single (last wins)
+ *   before:<date>   → approxidate upper bound, single
+ *   "..."           → quoted span: exact value after a prefix, or exact text
+ *   unknown:prefix  → an ordinary word (lenient, like IDEA)
+ *
+ * Only DATE values auto-extend over following words ("after:2 weeks ago") —
+ * approxidate is naturally multi-word. user/path take their inline value;
+ * names with spaces come from the popup or quotes.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/log-filter-query
+ */
+
+import type { LogFilter } from '../log-filter.ts'
+
+/** The filter that filters nothing. */
+export function emptyQueryFilter(): LogFilter {
+  return { users: [], text: '', textRegex: false, paths: [], after: '', before: '' }
+}
+
+/** Criterion kinds a chip can represent. */
+export type ChipKind = 'user' | 'path' | 'after' | 'before' | 'text'
+
+/** One removable criterion, as shown under the filter box. */
+export interface FilterChip {
+  readonly kind: ChipKind
+  readonly value: string
+}
+
+const PREFIXES: readonly ChipKind[] = ['user', 'path', 'after', 'before']
+const PREFIX_RE = /^(user|path|after|before):(.*)$/i
+
+interface Token {
+  readonly value: string
+  readonly quoted: boolean
+  readonly kind?: ChipKind
+}
+
+function tokenize(query: string): Token[] {
+  const tokens: Token[] = []
+  let i = 0
+  while (i < query.length) {
+    while (i < query.length && /\s/.test(query[i]!)) i += 1
+    if (i >= query.length) break
+    if (query[i] === '"') {
+      const end = query.indexOf('"', i + 1)
+      const value = end === -1 ? query.slice(i + 1) : query.slice(i + 1, end)
+      tokens.push({ value, quoted: true })
+      i = end === -1 ? query.length : end + 1
+      continue
+    }
+    // `prefix:"value with spaces"` — the quote opens INSIDE the word, right
+    // after the colon, so the word scanner below must not eat it as text.
+    const prefixQuote = /^(user|path|after|before):"/i.exec(query.slice(i))
+    if (prefixQuote !== null) {
+      const kind = prefixQuote[1]!.toLowerCase() as ChipKind
+      const open = i + prefixQuote[0].length
+      const end = query.indexOf('"', open)
+      const value = end === -1 ? query.slice(open) : query.slice(open, end)
+      tokens.push({ value, quoted: true, kind })
+      i = end === -1 ? query.length : end + 1
+      continue
+    }
+    const start = i
+    while (i < query.length && !/\s/.test(query[i]!)) i += 1
+    const word = query.slice(start, i)
+    const match = PREFIX_RE.exec(word)
+    tokens.push(match === null
+      ? { value: word, quoted: false }
+      : { value: match[2]!, quoted: false, kind: match[1]!.toLowerCase() as ChipKind })
+  }
+  return tokens
+}
+
+/**
+ * Parse the box's text into a filter.
+ * @param query - raw box contents.
+ */
+export function parseLogQuery(query: string): LogFilter {
+  const tokens = tokenize(query)
+  const users: string[] = []
+  const paths: string[] = []
+  let text = ''
+  let after = ''
+  let before = ''
+
+  const textWords: string[] = []
+  let i = 0
+  while (i < tokens.length) {
+    const token = tokens[i]!
+    if (token.kind === undefined) {
+      textWords.push(token.value)
+      i += 1
+      continue
+    }
+    if (token.kind === 'user' || token.kind === 'path') {
+      const list = token.kind === 'user' ? users : paths
+      if (token.value.length > 0 && !list.includes(token.value)) list.push(token.value)
+      i += 1
+      continue
+    }
+    // Date bounds: approxidate is naturally multi-word, so an unquoted value
+    // swallows the bare words that follow, stopping at the next prefix token
+    // or a quoted span. A QUOTED base value is exact — no extension.
+    const parts: string[] = [token.value]
+    let j = token.quoted ? i : i + 1
+    while (j < tokens.length && tokens[j]!.kind === undefined && !tokens[j]!.quoted && tokens[j]!.value.length > 0) {
+      parts.push(tokens[j]!.value)
+      j += 1
+    }
+    const value = parts.join(' ').trim()
+    if (token.kind === 'after') after = value
+    else before = value
+    i = token.quoted ? i + 1 : j
+  }
+  text = textWords.join(' ').trim()
+  return { users, text, textRegex: false, paths, after, before }
+}
+
+/** Quote a serialized value iff it would not reparse as itself. */
+function quote(value: string): string {
+  return /\s/.test(value) ? `"${value}"` : value
+}
+
+/**
+ * Render a filter back into the box's grammar. The text criterion goes last
+ * and is quoted when any of its words would parse as a prefix token.
+ * @param filter - the filter to render.
+ */
+export function serializeLogQuery(filter: LogFilter): string {
+  const parts: string[] = []
+  for (const user of filter.users) parts.push(`user:${quote(user)}`)
+  for (const path of filter.paths) parts.push(`path:${quote(path)}`)
+  if (filter.after.length > 0) parts.push(`after:${quote(filter.after)}`)
+  if (filter.before.length > 0) parts.push(`before:${quote(filter.before)}`)
+  if (filter.text.length > 0) {
+    const looksPrefixed = filter.text.split(/\s+/).some(word => PREFIX_RE.test(word))
+    parts.push(looksPrefixed ? `"${filter.text}"` : filter.text)
+  }
+  return parts.join(' ')
+}
+
+/**
+ * One chip per criterion, in grammar order: users, paths, bounds, text.
+ * @param filter - the filter to decompose.
+ */
+export function chipsFromFilter(filter: LogFilter): readonly FilterChip[] {
+  const chips: FilterChip[] = []
+  for (const user of filter.users) chips.push({ kind: 'user', value: user })
+  for (const path of filter.paths) chips.push({ kind: 'path', value: path })
+  if (filter.after.length > 0) chips.push({ kind: 'after', value: filter.after })
+  if (filter.before.length > 0) chips.push({ kind: 'before', value: filter.before })
+  if (filter.text.length > 0) chips.push({ kind: 'text', value: filter.text })
+  return chips
+}
+
+/**
+ * The filter minus one chip. Immutable; dropping the last criterion yields
+ * the empty filter.
+ * @param filter - current filter.
+ * @param kind - the chip's criterion kind.
+ * @param value - the chip's value (which user, which path).
+ */
+export function removeChip(filter: LogFilter, kind: ChipKind, value: string): LogFilter {
+  switch (kind) {
+    case 'user':
+      return { ...filter, users: filter.users.filter(user => user !== value) }
+    case 'path':
+      return { ...filter, paths: filter.paths.filter(path => path !== value) }
+    case 'after':
+      return { ...filter, after: '' }
+    case 'before':
+      return { ...filter, before: '' }
+    case 'text':
+      return { ...filter, text: '', textRegex: false }
+  }
+}

package/src/client/path-select.ts

@@ -0,0 +1,131 @@
+/**
+ * Checkbox-tree semantics for the path picker.
+ *
+ * Ticking a FOLDER means its whole subtree — so the selection is a set of
+ * pathspecs with an invariant: no member covers another. Ticking a folder
+ * absorbs the files already ticked inside it (the lone file's chip gives way
+ * to the folder's one); unticking one file under a checked folder cascades
+ * OUT — the folder is replaced by its other children, level by level. Rows
+ * then DERIVE their checkbox state (on / off / partial) from the set, which
+ * is why ticking a folder visibly checks everything under it.
+ *
+ * Pure throughout; the index is built from the same raw path list the host
+ * sent, so children order is the tree's alphabetical order.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/path-select
+ */
+
+/** Directory path → its direct children, full paths, files and dirs apart. */
+export interface PathIndex {
+  readonly dirs: ReadonlyMap<string, readonly string[]>
+  readonly files: ReadonlyMap<string, readonly string[]>
+}
+
+/**
+ * Index a raw path list for child lookup.
+ * @param paths - repo-relative file paths, exactly as `repoTree` returned.
+ */
+export function buildIndex(paths: readonly string[]): PathIndex {
+  const dirs = new Map<string, string[]>()
+  const files = new Map<string, string[]>()
+  const noteDir = (dir: string): void => {
+    if (!dirs.has(dir)) dirs.set(dir, [])
+  }
+  noteDir('')
+  for (const path of paths) {
+    if (path.length === 0) continue
+    const parts = path.split('/')
+    let dir = ''
+    for (let i = 0; i < parts.length - 1; i += 1) {
+      const childDir = dir === '' ? parts[i]! : `${dir}/${parts[i]!}`
+      noteDir(childDir)
+      const list = dirs.get(dir)!
+      if (!list.includes(childDir)) list.push(childDir)
+      dir = childDir
+    }
+    const list = files.get(dir) ?? []
+    list.push(path)
+    files.set(dir, list)
+  }
+  for (const list of dirs.values()) list.sort()
+  for (const list of files.values()) list.sort()
+  return { dirs, files }
+}
+
+/** Children of a directory, alphabetical by full path — the tree's order. */
+function childrenOf(index: PathIndex, dir: string): readonly string[] {
+  return [...(index.dirs.get(dir) ?? []), ...(index.files.get(dir) ?? [])].sort()
+}
+
+/**
+ * Is `p` selected — itself ticked, or inside a ticked directory?
+ * (Segment-boundary prefix: `src` does not cover `src2`.)
+ */
+export function isCovered(paths: readonly string[], p: string): boolean {
+  return paths.some(tick => tick === p || p.startsWith(`${tick}/`))
+}
+
+/**
+ * Tick a path. No-op when an ancestor already covers it; absorbs every
+ * descendant it covers, keeping the set minimal — one folder chip, never the
+ * pile of files under it.
+ */
+export function addPath(paths: readonly string[], p: string): readonly string[] {
+  if (isCovered(paths, p)) return paths
+  const kept = paths.filter(tick => !(tick === p || tick.startsWith(`${p}/`)))
+  return [...kept, p]
+}
+
+/**
+ * Untick a path. Removing an exact tick drops it; removing a file COVERED by
+ * a ticked folder replaces that folder with its other children, level by
+ * level down to the file — the standard cascade-out.
+ */
+export function removePath(paths: readonly string[], p: string, index: PathIndex): readonly string[] {
+  const out: string[] = []
+  for (const tick of paths) {
+    if (tick !== p && !p.startsWith(`${tick}/`)) {
+      out.push(tick)
+      continue
+    }
+    // This tick is p itself or an ancestor of it; replace it with the subtree
+    // minus p. Walk down the chain, adding each level's other children.
+    let dir = tick
+    while (dir !== p) {
+      // The child of `dir` on the way to p: the next path segment.
+      const rest = p.slice(dir.length + 1)
+      const nextName = dir === '' ? p.split('/')[0]! : rest.split('/')[0]!
+      const next = dir === '' ? nextName : `${dir}/${nextName}`
+      for (const child of childrenOf(index, dir)) {
+        if (child !== next) out.push(child)
+      }
+      dir = next
+    }
+  }
+  return out
+}
+
+/** Every file under a directory (empty for a file path). */
+function filesUnder(index: PathIndex, dir: string): readonly string[] {
+  const out: string[] = []
+  const stack = [dir]
+  while (stack.length > 0) {
+    const current = stack.pop()!
+    out.push(...(index.files.get(current) ?? []))
+    stack.push(...(index.dirs.get(current) ?? []))
+  }
+  return out
+}
+
+/**
+ * A row's checkbox state, derived: `on` when covered — by an ancestor tick OR
+ * by every file under it being covered individually; `partial` when a
+ * directory holds some but not all of its files; else `off`.
+ */
+export function checkedState(paths: readonly string[], p: string, index: PathIndex): 'on' | 'off' | 'partial' {
+  if (isCovered(paths, p)) return 'on'
+  const files = filesUnder(index, p)
+  if (files.length === 0) return 'off'
+  const covered = files.filter(file => isCovered(paths, file)).length
+  return covered === files.length ? 'on' : covered > 0 ? 'partial' : 'off'
+}

package/src/discard-ops.ts

@@ -0,0 +1,197 @@
+/**
+ * What "discard this file" resolves to, as a plan the host can carry out.
+ *
+ * This is the confirmation design `git-ops.ts` says a destructive button owes
+ * before it may exist. Three rules hold here, and each one closes a way this
+ * feature could quietly destroy the wrong thing:
+ *
+ *   - **The plan is derived from git's OWN report of the file, never from what
+ *     the client said it was.** A client that mislabels a tracked file as
+ *     untracked would otherwise turn a restore into a delete. `planFor` takes
+ *     a porcelain XY pair that the host read itself.
+ *   - **No plan may contain a destructive spelling.** Not `clean`, not
+ *     `reset --hard`, not `checkout -f`, no `--force`. `git restore` scoped to
+ *     one pathspec after `--` is the whole vocabulary; a stray `clean` would
+ *     take out every untracked file in the tree instead of the one named.
+ *     `tests/discard-ops.test.ts` scans every plan this module can produce.
+ *   - **A path that is deleted from disk is checked far harder than a
+ *     pathspec.** git refuses to leave the repository; `fs.rm` does not, so
+ *     `isSafeRelativePath` rejects absolutes, drive letters, UNC prefixes and
+ *     any `..` segment before a delete step can name a file.
+ *
+ * IDEA parity decides the semantics: Rollback there takes a file back to its
+ * committed state in one gesture and does not ask whether the change was
+ * staged, so neither does this. A file that was never committed goes away; a
+ * file that was deleted comes back.
+ *
+ * Pure throughout — no spawning, no fs. `src/index.ts` executes the steps.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/discard-ops
+ */
+
+import { isSafePathArg, parseStatusLine } from './git-ops.js'
+
+/** One thing the host does, in order. */
+export type DiscardStep =
+  /** Run git with this argv. */
+  | { readonly kind: 'git'; readonly argv: readonly string[] }
+  /** Remove this repo-relative path from disk. Tolerates an absent file. */
+  | { readonly kind: 'delete'; readonly path: string }
+
+/**
+ * What the reader is about to lose, which is what the confirmation must say.
+ * The client maps these to copy; keeping them as data means the wording can be
+ * bilingual without this module knowing about locales.
+ */
+export type DiscardEffect =
+  /** Tracked file returns to its committed content. Local edits are gone. */
+  | 'restore'
+  /** File leaves the disk. git never had it, so nothing can bring it back. */
+  | 'delete'
+  /** A deleted file comes back. Nothing is lost — no confirmation needed. */
+  | 'recover'
+  /** A rename is undone: the old path returns, the new one goes. */
+  | 'unrename'
+
+export interface DiscardPlan {
+  readonly steps: readonly DiscardStep[]
+  readonly effect: DiscardEffect
+  /**
+   * Whether carrying this out can lose work no git object holds. Drives
+   * whether the client confirms at all: recovering a deleted file is pure
+   * gain, and a dialog in front of it is noise that teaches people to click
+   * through dialogs.
+   */
+  readonly irreversible: boolean
+  /** The path the reader named, for the confirmation copy. */
+  readonly path: string
+  /** For `unrename`, the path the file is going back to. */
+  readonly previousPath?: string
+}
+
+/**
+ * Whether a path is safe to hand a filesystem delete.
+ *
+ * Stricter than {@link isSafePathArg}, which only has to keep git from reading
+ * a path as an option: git will not step outside the repository whatever it is
+ * given, so a pathspec needs no traversal check. A delete has no such backstop.
+ * Rejected: absolute paths (POSIX and Windows), UNC prefixes, drive letters,
+ * NUL bytes, and any `..` segment — including one buried mid-path, which is
+ * how traversal is usually spelled.
+ * @param path - repo-relative path from a plan step.
+ */
+export function isSafeRelativePath(path: string): boolean {
+  if (!isSafePathArg(path)) return false
+  if (path.includes('\0')) return false
+  // Windows accepts both separators, so normalise before splitting or
+  // `a\..\..\b` walks out through a check that only knew about `/`.
+  const unified = path.replace(/\\/g, '/')
+  if (unified.startsWith('/')) return false
+  if (/^[A-Za-z]:/.test(unified)) return false
+  if (unified.startsWith('//')) return false
+  return !unified.split('/').includes('..')
+}
+
+/** Take one file back to HEAD in both the index and the working tree. */
+function restoreBoth(path: string): DiscardStep {
+  return { kind: 'git', argv: ['restore', '--source=HEAD', '--staged', '--worktree', '--', path] }
+}
+
+/** Drop a file's index entry, leaving the working tree untouched. */
+function unstage(path: string): DiscardStep {
+  return { kind: 'git', argv: ['restore', '--staged', '--', path] }
+}
+
+/**
+ * The plan for one file, from git's own porcelain line.
+ *
+ * @param xy - the two porcelain status columns for this path, e.g. ` M`, `??`,
+ *             `R `. Read by the host from `git status --porcelain`, never
+ *             supplied by the client.
+ * @param path - repo-relative path, as git printed it.
+ * @param previousPath - for a rename, the path HEAD still knows the file by.
+ * @returns the ordered plan, or null when the file has nothing to discard.
+ * @throws if a path is not safe to pass on.
+ */
+export function planFor(xy: string, path: string, previousPath?: string): DiscardPlan | null {
+  if (!isSafePathArg(path)) throw new Error(`unsafe path argument: ${JSON.stringify(path)}`)
+  const index = xy[0] ?? ' '
+  const worktree = xy[1] ?? ' '
+
+  // Untracked and ignored: git has no copy, so the only way back is the
+  // filesystem's, and there is none.
+  if (xy === '??' || xy === '!!') {
+    if (!isSafeRelativePath(path)) throw new Error(`unsafe path to delete: ${JSON.stringify(path)}`)
+    return { steps: [{ kind: 'delete', path }], effect: 'delete', irreversible: true, path }
+  }
+
+  // A rename: HEAD holds `previousPath`, the index holds `path`. Bring the old
+  // one back first, then retire the new one — doing it the other way round
+  // would leave the tree with neither name for as long as the second step
+  // takes, which a reader watching a file tree would see.
+  if (index === 'R' || index === 'C') {
+    if (previousPath === undefined || !isSafePathArg(previousPath)) {
+      throw new Error(`rename without a usable previous path: ${JSON.stringify(path)}`)
+    }
+    if (!isSafeRelativePath(path)) throw new Error(`unsafe path to delete: ${JSON.stringify(path)}`)
+    return {
+      steps: [restoreBoth(previousPath), unstage(path), { kind: 'delete', path }],
+      effect: 'unrename',
+      irreversible: true,
+      path,
+      previousPath,
+    }
+  }
+
+  // Added to the index but absent from HEAD: rolling back means the file was
+  // never committed, so it leaves. Unstage first — otherwise the index would
+  // still carry an entry for a path that no longer exists on disk.
+  if (index === 'A') {
+    if (!isSafeRelativePath(path)) throw new Error(`unsafe path to delete: ${JSON.stringify(path)}`)
+    return {
+      steps: [unstage(path), { kind: 'delete', path }],
+      effect: 'delete',
+      irreversible: true,
+      path,
+    }
+  }
+
+  // Deleted, either side. HEAD still has the content, so this is recovery:
+  // nothing is lost and nothing needs confirming.
+  if (index === 'D' || worktree === 'D') {
+    return { steps: [restoreBoth(path)], effect: 'recover', irreversible: false, path }
+  }
+
+  // Everything else that git reported as changed — modified, type-changed,
+  // staged, unstaged, or both — goes back to HEAD wholesale. Content only the
+  // working tree ever held has no object behind it.
+  if (index !== ' ' || worktree !== ' ') {
+    return { steps: [restoreBoth(path)], effect: 'restore', irreversible: true, path }
+  }
+
+  // Clean: git reported the path with nothing to say about it.
+  return null
+}
+
+/**
+ * Find the file in a status report and plan for it.
+ *
+ * The report is the WHOLE tree's, not one narrowed by a pathspec: git detects
+ * a rename by pairing a deletion with an addition, and a pathspec that admits
+ * only one of the pair turns `R old -> new` into an unrelated `D` and `??`.
+ * The plan for those two is delete-and-lose where the truth is un-rename.
+ *
+ * @param stdout - `git status --porcelain=v1` over the whole worktree.
+ * @param path - the file the reader asked about, as the drawer lists it.
+ * @returns the plan, or null when git does not report that path as changed —
+ *          which is also what a stale tree looks like, and is not an error.
+ */
+export function planFromStatus(stdout: string, path: string): DiscardPlan | null {
+  if (!isSafePathArg(path)) throw new Error(`unsafe path argument: ${JSON.stringify(path)}`)
+  for (const line of stdout.split('\n')) {
+    const parsed = parseStatusLine(line)
+    if (parsed === null || parsed.path !== path) continue
+    return planFor(parsed.xy, parsed.path, parsed.renamed ? parsed.previousPath : undefined)
+  }
+  return null
+}