Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(vendor): catalog skim 4.x upgrade impact and stability assessment (#2239)
Maximilian Roos7dc78c948a5d
diff --git a/vendor/NOTES.md b/vendor/NOTES.mdindex e7dc132be..2cfe5afde 100644--- a/vendor/NOTES.md+++ b/vendor/NOTES.md@@ -49,3 +49,75 @@ These are workarounds in our crate that exist because we couldn't change skim. N3. Run `task vendor-diff` and confirm the diff is minimal and readable.4. Move the entry above from "Candidate future patches" to "Landed" with the upstream tracking link.5. Open an upstream PR against skim-rs/skim — the goal is always to stop carrying the patch.++## Skim 4.x upgrade impact (verified 2026-04-14 against v4.6.0)++We currently pin skim 0.20.5. The 4.x line is a substantial rewrite — most of our candidate patches above become unnecessary, but the upgrade itself is a project. Findings from reading `github.com/skim-rs/skim` at tag `v4.6.0` (clone at `~/workspace/skim`):++### Architecture changes relevant to our patches++- **tuikit is gone.** 4.x depends on `ratatui = "0.30"` + `crossterm` directly; there is no `skim-tuikit` crate in its dep graph. `src/tui/` is the internal TUI module. Our `vendor/skim-tuikit/` patch tree becomes orphaned — nothing to rebase onto.+- **ANSI parser replaced.** The homegrown `ANSIParser` is gone; `ansi-to-tui = "8.0.1"` handles ANSI in `src/tui/{header,input,preview,util}.rs`. SGR handling moves to that crate's responsibility.+- **Preview model rewritten.** `src/tui/preview.rs` uses `portable_pty` for command-based previews, runs them on a dedicated thread (`thread_handle: Option<JoinHandle<()>>`), and renders via `tui_term::vt100` + `ratatui`. UI thread is no longer blocked on preview compute.+- **Public event channel.** `Skim::event_sender() -> tokio::sync::mpsc::Sender<Event>` (src/skim.rs:321) hands out a sender any background thread can push into. `Event::RunPreview` is a public variant of the public `Event` enum (src/tui/event.rs:144).+- **Async action callbacks.** `ActionCallback::new` / `new_sync` accept async or sync closures receiving `&mut App` (src/tui/event.rs:54–108). Custom actions get direct mutable access to app state instead of going through side channels.+- **`SkimItem::preview()` unchanged** — still `fn preview(&self, _context: PreviewContext) -> ItemPreview`. Sync, same variants (`Text`/`AnsiText`/`Command`/`Global`/…).+- **`SkimItem::display()` changed.** Returns `ratatui::text::Line<'_>` instead of `AnsiString<'_>`. Our `WorktreeSkimItem::display()` impl needs rewriting against ratatui.+- **`SkimItem::get_index` / `set_index` removed** (4.0). We don't implement them, so zero impact.+- **Default matcher algorithm changed** to "Arinae" (typo-resistant off by default). Our ranking snapshots and picker-perf benchmarks will shift.+- **`AsAny` blanket impl in skim's lib** (src/lib.rs:101–116). The documented downcast example in the new `SkimItem` docstring uses it successfully — the TypeId-mismatch bug we hit is **likely** fixed by the consolidated crate structure. Needs empirical verification on our actual item type.++### Per-patch fate under a 4.x upgrade++| Patch | Status in 4.x | Action on upgrade |+|---|---|---|+| **Preview refresh / invalidate** (this memo's topic) | **Solved natively.** Push `Event::RunPreview` via `Skim::event_sender()` when cache lands. | Drop from candidate list; rewrite picker to use `event_sender()`. |+| **Async preview / thread-safe preview API** | **Solved.** Previews run on dedicated thread + PTY. | Drop. `DashMap` for cache is still fine but no longer motivated by UI-thread contention. |+| **SGR 22 (intensity reset) handling** | **Offloaded to `ansi-to-tui` 8.0.1.** Our skim-side fix is no longer applicable. Needs empirical check that `color_print`'s `</>` output renders correctly through `ansi-to-tui`. | Re-test the preview-tab header + `compute_*_preview` output. If `ansi-to-tui` handles 22 correctly, delete the `Reset` scatter in `items.rs`. |+| **Action context for `reload` / `refresh-preview`** | **Solved.** `ActionCallback::new_sync(|app| …)` gives direct `&mut App`. | Drop the two temp-file side channels (`src/commands/picker/preview.rs`, `src/commands/picker/mod.rs:435,508-511`). Wire a real callback. |+| **TypeId-mismatch downcast** | **Probably solved** by consolidated compilation + blanket `AsAny`. | Test first: if `as_any().downcast_ref::<WorktreeSkimItem>()` returns `Some`, delete the `output()`-string-match fallback in `src/commands/picker/mod.rs:217-220`. |+| **Off-thread `CommandCollector::invoke`** | **Probably solved.** The trait may have been restructured around `ActionCallback` / async runtime. Needs concrete check of the new collector API. | Re-evaluate against the 4.x `App` + `ActionCallback` surface. |+| **Cwd-independent skim** | Unverified — no release note mentions it. | Check empirically after upgrade. |+| **Landed: `Output::flush` write_all (tuikit)** | **Orphaned.** `src/output.rs` in 4.x is a different file (final selection output, not terminal output). Terminal output is `ratatui::Terminal` over `CrosstermBackend<BufWriter<Stderr>>` — our tuikit fix doesn't apply. Upstream PR [#1056](https://github.com/skim-rs/skim/pull/1056) is against the 0.x line. | Drop the vendored `skim-tuikit` tree entirely. |+| **In-flight: smcup/rmcup symmetry in partial-height mode** | Orphaned same reason — tuikit is gone. | Re-evaluate the symptom against 4.x's ratatui-based alt-screen handling before reinventing. |++### Net cost/benefit++- **If we upgrade to 4.x first:** every open skim-side patch except possibly cwd-independence becomes unnecessary. `vendor/skim-tuikit/` can be deleted. Carrying zero vendor patches against skim is achievable.+- **If we patch 0.20.5 now:** the preview-refresh fix is ~15 vendored LOC in `previewer.rs` + `model/mod.rs`. Cheap to carry until we migrate.+- **4.x migration cost on our side** (not the vendor tree): rewrite `WorktreeSkimItem::display()` for `ratatui::text::Line`, re-snapshot picker ranking tests (matcher default changed), re-test ANSI rendering through `ansi-to-tui`, re-wire actions to `ActionCallback` (potentially big simplification, potentially churn). Non-trivial but bounded.++### Stability assessment — don't vendor yet (2026-04-14)++Considered vendoring skim 4.x ourselves with loosened dep pins. Decided **not yet**. Reasons:++- **Upstream is already fixing the pinning problem.** [skim-rs/skim#1050](https://github.com/skim-rs/skim/issues/1050) was filed 2026-04-13 and closed 2026-04-14 with maintainer LoricAndre committing to loosen pins on widely-used deps and ship a release "today or tomorrow." Our primary rationale for vendoring (unpinning `=X.Y.Z` constraints on ~17 deps) evaporates if that release delivers. Re-check after next release — if pins are livable, migrate against crates.io skim with zero vendor cost.+- **4.x is a young rewrite, stabilizing but not stable.** Bug intake by month (`bug`-labeled issues, 4.x era): 25 (Jan), 12 (Feb), 5 (Mar), 2 (Apr half-month). Declining sharply. But the cohort touches exactly our surface area: PTY preview hangs ([#951](https://github.com/skim-rs/skim/issues/951)), PTY changes cwd ([#950](https://github.com/skim-rs/skim/issues/950)), runaway thread loop ([#949](https://github.com/skim-rs/skim/issues/949)), matcher flake ([#947](https://github.com/skim-rs/skim/issues/947)), preview runs once per invocation ([#944](https://github.com/skim-rs/skim/issues/944)), some ANSI codes wrong in preview ([#964](https://github.com/skim-rs/skim/issues/964)). All closed, all within the last 8 weeks.+- **Open concern**: [#988](https://github.com/skim-rs/skim/issues/988) `MatchedItem should be Weak<dyn SkimItem>` — lifecycle/cycle bug, still open, affects how picker items live and die. Track before migrating.+- **Release cadence is ~2/week.** Eight 4.x releases in April alone. Vendoring a crate that ships this often means rebasing our fork every few days — materially more expensive than the current `vendor/skim-tuikit/` tree (which hasn't shipped since Aug 2025, hence zero rebase cost). Vendoring an abandoned crate is cheap; vendoring an actively-developed one is not.+- **Bus factor of 1.** LoricAndre is doing nearly all substantive PRs. Responsive today, but if responsiveness vanishes, we'd inherit a live project.++### Recommended sequence++1. **This week**: watch for the next skim release (v4.7.0-ish) carrying the #1050 pin-loosening. Check whether our dep graph resolves against unpinned crates.io 4.x.+2. **Next 4–8 weeks**: let the 4.x bug tail drain further and watch bug-intake rate. If it stays at ≤2/month, 4.x is stabilized enough to build on.+3. **When ready, migrate without vendoring**: do the picker-side rewrite (display → `Line`, actions → `ActionCallback`, re-snapshot rankings, retest ANSI). Depend on crates.io skim. This is the best outcome — zero vendor patches against skim.+4. **Fallback if upstream re-pins or MSRV conflicts**: the ~17-line unpin patch is trivially small and always available. We lose nothing by deferring.++**For the current preview-refresh bug** that motivated this memo: ship the internal cache-refresh design (Option B+D2+C2+placeholder from the design doc, ~90 LOC, no vendor change). Accept the keypress-to-redraw limitation. By the time we'd have a skim vendor patch merged and rebased, 4.x will likely be mature enough to migrate to natively — and migration gives us `event_sender()` + `Event::RunPreview` for free.++### Verification method++All architectural claims in this section were verified by reading source at tag `v4.6.0` in `~/workspace/skim`. To re-verify after future skim releases:++```bash+cd ~/workspace/skim && git fetch upstream --tags && git worktree add /tmp/skim-<ver> v<ver>+# then grep for: pub event_sender, Event::RunPreview, SkimItem trait, ansi_to_tui usage+```++Bug-intake check for stability re-assessment:++```bash+gh issue list --repo skim-rs/skim --limit 200 --state all --json number,createdAt,state,labels \+ --jq '[.[] | select(.labels | map(.name) | index("bug"))] | group_by(.createdAt[:7]) | map({month: .[0].createdAt[:7], count: length})'+```