Skip to content

refactor(picker): migrate to skim 4.8 (ratatui), drop vendored skim-tuikit - #3137

Merged
max-sixty merged 4 commits into
mainfrom
upgrade-skim
Jun 20, 2026
Merged

max-sixty merged 4 commits into
mainfrom
upgrade-skim

Conversation

@max-sixty

@max-sixty max-sixty commented Jun 20, 2026 •

Copy link
Copy Markdown
Owner

Migrates the wt switch picker from skim 0.20.5 (tuikit backend) to skim 4.8.0 (ratatui/crossterm), removes the vendor/skim-tuikit/ patch tree we carried against the old line, and makes the full test suite green under the new backend.

Why the vendor tree goes away

We vendored skim-tuikit for two patches: alt-<digit> key parsing and an Output::flush write_all fix for dropped bytes under PTY pressure. Both are moot in 4.8. Key parsing is native — binds.rs routes every single character (digits included) through KeyCode::Char rather than a hardcoded alt-a..alt-z arm list. The flush fix is subsumed by stdlib BufWriter::flush in the ratatui backend, which loops over partial writes correctly. So the migration carries zero vendor patches against skim, and the build machinery that kept the vendored source alive (Taskfile vendor-diff, flake vendorSrc/extraDummyScript) is deleted too.

The picker rewrite

skim 4.x is a different API. WorktreeSkimItem::display() now returns ratatui::text::Line instead of an AnsiString. alt-r removal rides skim's reload(remove {}) token (the selected row's output(), expanded into the reload command) instead of the old as_any().downcast_ref path (which never worked across compilation units) plus a signal file. Preview-tab switching and the progressive list redraw are driven by Skim::event_sender() + Event::Render/Event::RunPreview.

The regression that motivated the bulk of this

skim 4.x renders on demand. There is no 100ms tuikit heartbeat re-rendering the frame, so the progressive wt switch list rendered blank while collection ran in the background — the original report. The fix pokes Event::Render from the list-collect callbacks (throttled to 16ms). The same on-demand model surfaced four more regressions, all fixed here and verified head-to-head against the 0.20 picker in a terminal: preview-tab lag, current-row highlight, Shift-Tab back-cycle (crossterm reports Shift-Tab under three distinct KeyEvent shapes, so all three are bound), and alt-r removal (4.x execute-silent is fire-and-forget and raced its reader).

Help text and the test harness

Two things the integration suite caught that the unit tests did not (the prior pass ran --lib --bins only):

  • Styled help. skim 0.20 transitively pulled in clap/unstable-markdown, which renders worktrunk's /// doc-comments as styled help. skim 4 with default-features = false drops it, so help reverted to raw text ([experimental] → \[experimental\]). Restored by depending on unstable-markdown explicitly, keeping help output identical and the test_help / test_step_alias / test_docs_are_in_sync snapshots passing unchanged.
  • PTY harness. skim 4.x queries cursor position (ESC[6n) at startup in partial-height mode and blocks in select() for the reply; portable_pty is a bare PTY and never answered, so every switch_picker test failed init with "Cursor position detection timed out." The Unix harness now answers the query, mirroring the existing ConPTY responder. skim 4.x also draws the list/preview separator one column left, so the snapshot panel-split columns shifted to match. The regenerated picker snapshots show two cosmetic changes: the match counter no longer overlaps the preview tab header, and the HEAD column shows the full short-SHA instead of a truncated one.

Minimal-versions CI

The skim 4.8 dep tree pins tighter floors than our manifests declared, so the nightly minimal-versions job needed updating. It now runs -Z direct-minimal-versions — minimize only our own direct deps and let transitive crates resolve normally — and the manifests raise each under-specified floor to the minimum the workspace builds against (largely mirroring skim 4.8's own requirements). Full -Z minimal-versions would instead drag in skim's transitive TUI/image stack (ansi-to-tui, ratatui's instability macro, color-eyre, ratatui-image → image/avif), whose crates under-declare their floors and don't compile at the picked versions; direct minimization confines the check to floors we own, so no transitive pins are needed. Normal resolution (the committed Cargo.lock) is unchanged. Full floor list and the signal-hook libc-pin detail are in the ci(min-versions) commit message.

Reviewing

Start at src/commands/picker/mod.rs (the run_skim entry point, the action keybinds, and parse_reload_remove_token), then progressive_handler.rs (the render pokes) and items.rs (the Line-based display()). Test-harness changes are in tests/common/pty.rs (the ESC[6n responder) and tests/integration_tests/switch_picker.rs (the panel-split columns). The rest is the dependency swap, the vendor and build-machinery deletions, and regenerated snapshots.

All 3980 tests pass (cargo run -- hook pre-merge --yes), including the shell-integration-tests PTY suite that exercises the picker end-to-end across the list, previews, scroll, create/remove, and accept flows. No automated test drives a real terminal; the interactive surface was also checked by hand against the 0.20 picker.

This was written by Claude Code on behalf of max

max-sixty and others added 2 commits June 19, 2026 21:21
…uikit

Replace skim 0.20.5 (tuikit backend) with skim 4.8.0 (ratatui/crossterm).
Delete the vendor/skim-tuikit patch tree and its build machinery (Taskfile
vendor-diff, flake vendorSrc/extraDummyScript). Both carried patches are moot
in 4.8: alt-<digit> key parsing is native (binds.rs routes every single char
through KeyCode::Char), and the Output::flush write_all fix is subsumed by
stdlib BufWriter::flush in the ratatui backend.

Rewrite the picker against the 4.x API. WorktreeSkimItem::display() returns
ratatui::Line. alt-r removal rides skim's reload(remove {}) token instead of
the removed downcast path plus a signal file. Preview-tab switching and the
progressive list are driven by Skim::event_sender() + Event::Render/RunPreview.

skim 4.x renders on demand (there is no 100ms tuikit heartbeat), so the
progressive `wt switch` list rendered blank during collection. Poke
Event::Render from the collect callbacks (throttled to 16ms) to restore it.
The same on-demand model surfaced four more regressions, all fixed here:
preview-tab lag, current-row highlight, Shift-Tab back-cycle (crossterm reports
Shift-Tab under three KeyEvent shapes, so bind all three), and alt-r removal
(execute-silent is fire-and-forget in 4.x and raced its reader).

Restore styled help. skim 0.20 transitively enabled clap/unstable-markdown,
which renders our `///` doc-comments as styled help; skim 4
(default-features = false) drops it, reverting help to raw text. Depend on it
explicitly to keep help output identical.

Update the integration-test harness for the 4.x picker:
- skim 4.x queries cursor position (ESC[6n) at startup in partial-height mode.
  The Unix PTY harness now answers it, mirroring the existing ConPTY responder;
  without a reply skim's select() times out and the picker never initializes.
- skim 4.x draws the list/preview separator one column left (col 59), so the
  panel-split capture columns shifted to match.
- Regenerate the picker TUI snapshots: the match counter no longer overlaps the
  preview tab header, and the HEAD column shows the full short-SHA.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
# Conflicts:
#	src/commands/picker/mod.rs

@worktrunk-bot worktrunk-bot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the skim 0.20 → 4.x migration. The mechanics — reload(remove {}) replacing the raced execute-silent+signal-file (which under skim 4.x could remove the wrong worktree on a repeat alt-r), run_skim inlining init/run to grab event_sender() for on-demand repaints, the ModeWatcher for tab-switch preview refresh, and the PTY test harness answering skim's ESC[6n cursor query — all read as carefully reasoned and well-documented. Two things below.

1. minimal-versions is failing on this PR's new deps. Not transient — it's a deterministic under-constraint introduced by ansi-to-tui. The new ansi-to-tui 8.0.1 declares simdutf8 = "^0.1", but the impl std::error::Error/Display for Utf8Error that its thiserror::Error derive depends on only landed in simdutf8 0.1.1 (changelog: "Make both Utf8Error variants implement std::error::Error" under 0.1.1). -Z minimal-versions resolves ^0.1 down to 0.1.0, so cargo check fails with Utf8Error doesn't implement std::fmt::Display (run).

The usual floor-pin fixes it — add to [target.'cfg(unix)'.dependencies]:

# minimal-versions floor: ansi-to-tui 8 declares `simdutf8 = "0.1"`, but the
# `Utf8Error: std::error::Error` impl its thiserror derive needs only lands in
# simdutf8 0.1.1. Pin the floor so `-Z minimal-versions` resolves a usable
# version. Pulled only transitively (hence the cargo-udeps ignore).
simdutf8 = { version = "0.1.1", optional = true }

plus "dep:simdutf8" in the cli feature and a normal/optional entry under [package.metadata.cargo-udeps.ignore] so check-unused-dependencies stays green. Happy to push that commit if you'd like — there's enough leeway in how the floor is wired (optional vs. plain, which udeps bucket) that I left it for you rather than guessing your preference.

2. Data-safety note (not blocking): this edits the alt-r removal path (picker/mod.rs still drives delete_branch_if_safe and worktree removal via prepare_removal). The destructive primitives themselves are untouched and the change is a net safety improvement, but per the repo's data-loss-surface policy I'm not auto-approving picker-removal edits — flagging it for the record rather than rubber-stamping.

One inline doc-comment fix below.

Comment thread src/commands/picker/mod.rs Resolved
The run_skim doc block was left attached to `struct ModeWatcher` when the
watcher was inserted above the function; the real run_skim has its own doc.
Addresses review feedback on #3137.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… stack

The skim 0.20 -> 4.8 migration brought a TUI/image dependency tree whose
crates pin tighter floors than worktrunk's manifests declared. Run the
minimal-versions CI job with `-Z direct-minimal-versions` (minimize only our
own direct deps; let transitive crates resolve normally) and raise each
under-specified floor to the minimum the workspace builds against.

Full `-Z minimal-versions` would also minimize skim's transitive TUI/image
stack (ansi-to-tui's simdutf8, ratatui's instability macro, color-eyre's
eyre, ratatui-image -> image/avif -> num-* and bitvec), whose crates
under-declare their own floors and don't compile at the picked versions --
upstream brokenness we'd have to pin around. Direct minimization confines
the check to floors we own.

worktrunk direct-dep floors (largely mirroring skim 4.8's own requirements):
  anyhow 1.0.102, anstyle 1.0.13, log 0.4.31, tracing 0.1.35, serde 1.0.228,
  serde_json 1.0.145, strsim 0.11.1, terminal_size 0.4.3, unicode-width
  0.2.1, once_cell 1.21.4, which 8.0.2, regex 1.12.3, ansi-to-tui 8.0.1,
  tokio 1.52.3, nix 0.31.3, vt100 0.16.2 (dev).

  signal-hook 0.4.1: 0.4.0 pins `libc =0.2.156`, which conflicts with nix
  0.31.3's `libc ^0.2.186`; 0.4.1 relaxes it to `^0.2`.

  skim 4.8 / ratatui 0.30.1 / chrono 0.4.31 carry over from the migration:
  the picker is written against 4.8's ratatui 0.30.1 API; ratatui 0.30.0 is
  a broken release (its `#[instability::unstable]` attribute fails to
  compile); `DateTime::from_timestamp` (utils.rs, statusline.rs, backup.rs)
  landed in chrono 0.4.31.

Test helpers checked by `--workspace --all-targets` get matching floors:
  mock-stub (serde 1.0.228, serde_json 1.0.145) and wt-perf (clap 4.6,
  serde_json 1.0.145, insta 1.47.2).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@max-sixty
max-sixty merged commit 958b9c1 into main Jun 20, 2026
36 checks passed
@max-sixty
max-sixty deleted the upgrade-skim branch June 20, 2026 10:41
max-sixty added a commit that referenced this pull request Jun 21, 2026
Reconcile the live-CI-fetch + `--prs` picker work with main's skim 4.x
(ratatui/crossterm) migration (#3137), which rewrote the picker's skim
integration and dropped the vendored skim-tuikit tree.

Key reconciliations:
- Port `PrSkimItem` to skim 4.x: `display()` returns a ratatui `Line` via
  the shared `ansi_to_line` helper (not `skim::AnsiString`), and the
  `--prs` thread sends one batched `Vec<Arc<dyn SkimItem>>` (skim 4.x's
  channel takes batches, not single items).
- `on_update` writes the live `pr_status` slot, then pokes main's
  `request_render` (skim 4.x repaints on demand; the 100ms heartbeat is
  gone). The pr tab still can't be re-queried mid-selection, so its
  "press alt-6 to refresh" hint stays.
- Fix the Shift-Tab rotation: main added `shift-btab`/`shift-tab` bindings
  with the old 5-tab `tr 12345 51234`; bump them to the 6-tab
  `tr 123456 612345` so Shift-Tab wraps 1 -> pr (6), not 1 -> summary (5).
- Drop the stale skim-0.20.5 / vendor/NOTES.md SGR-22 and heartbeat
  comments; keep the explicit `\x1b[0m` reset (still needed).
- Regenerate the 11 picker PTY snapshots for skim 4.x rendering (border at
  col 59, `[N/M]` match counter) plus the CI column and pr tab.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@max-sixty max-sixty mentioned this pull request Jun 21, 2026
social4hyq pushed a commit to social4hyq/homebrew-core that referenced this pull request Sep 20, 2026
worktrunk 0.61.0

Created-by: HarmonybrewBot
Commit-by: HarmonybrewBot
Merged-by: HarmonybrewBot
Description: Created by `brew bump`

---

Created with `brew bump-formula-pr`.<details>
  <summary>release notes</summary>
  <pre>## Release Notes

### Improved

- **`wt list` custom columns**: Each `[list.custom-columns.<Header>]` entry in user config adds a column to `wt list` (and the `wt switch` picker), rendered per row as a minijinja template over `branch`, `worktree_path`, `worktree_name`, and `vars.*`, with optional `width` and drop priority. Values expand from in-memory data only — no subprocess runs per cell — and a column that is empty on every row is dropped. `wt list --format=json` gains a `columns` map per item. The feature is experimental, so the config shape may still change. ([#3073](max-sixty/worktrunk#3073))

- **`--config-set` for inline config overrides**: A global, repeatable `--config-set <toml>` flag overrides any user-config key for a single invocation, layered above config files and `WORKTRUNK_*` env vars. The value is a real TOML fragment, so arrays and tables work natively (`wt --config-set list.full=true list`); nested tables deep-merge, and a malformed or invalid override drops the whole `--config-set` layer with an attributed warning rather than failing the command. ([#3138](max-sixty/worktrunk#3138))

- **Picker shows cached PR/MR numbers**: The `wt switch` picker skips the networked CI-status fetch, so it previously had no CI column. It now fills PR/MR numbers from the local `.git/wt/cache/ci-status/` cache populated by earlier `wt list --full` or statusline runs, with zero network access. A stale entry (TTL passed or branch head moved) keeps its number dimmed; expired entries without a number are dropped. ([#3073](max-sixty/worktrunk#3073))

- **Faster file copies on macOS**: After a reflink (`clonefile` on APFS, which already preserves mode bits), worktrunk now skips the redundant follow-up `chmod` on macOS, saving one syscall per file in `wt step copy-ignored` and every other copy path. Linux (btrfs/XFS) still sets permissions, since `FICLONE` clones data extents only and drops the execute bit. ([#3149](max-sixty/worktrunk#3149))

### Internal

- **Picker migrated to skim 4.8 (ratatui/crossterm)**: The `wt switch` picker moved off skim 0.20.5 (tuikit) to skim 4.8.0, dropping the vendored `vendor/skim-tuikit/` patch tree (both patches it carried are now native or upstream). Two cosmetic picker changes come with it: the match counter no longer overlaps the preview-tab header, and the HEAD column shows the full short-SHA. ([#3137](max-sixty/worktrunk#3137))

- **All command spawns route through one trace chokepoint**: `CommandTrace` is now the sole emitter of `[wt-trace]` command records, so a spawn path can't silently skip tracing — `git worktree add`, previously an unattributed gap, now shows up as a labeled slice in `wt-perf timeline`. ([#3134](max-sixty/worktrunk#3134))

### Documentation

- **Hook-approval skill guidance**: The bundled worktrunk skill now frames hook approvals as user consent and no longer advocates `--yes` to bypass prompts. ([#3146](max-sixty/worktrunk#3146))

## Install worktrunk 0.61.0

### Install prebuilt binaries via shell script

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-installer.sh | sh && wt config shell install
```

### Install prebuilt binaries via powershell script

```sh
powershell -ExecutionPolicy Bypass -c "irm https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-installer.ps1 | iex"; git-wt config shell install
```

### Install prebuilt binaries via Homebrew

```sh
brew install worktrunk && wt config shell install
```

## Download worktrunk 0.61.0

|  File  | Platform | Checksum |
|--------|----------|----------|
| [worktrunk-aarch64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-aarch64-apple-darwin.tar.xz) | Apple Silicon macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-aarch64-apple-darwin.tar.xz.sha256) |
| [worktrunk-x86_64-apple-darwin.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-x86_64-apple-darwin.tar.xz) | Intel macOS | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-x86_64-apple-darwin.tar.xz.sha256) |
| [worktrunk-x86_64-pc-windows-msvc.zip](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-x86_64-pc-windows-msvc.zip) | x64 Windows | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-x86_64-pc-windows-msvc.zip.sha256) |
| [worktrunk-aarch64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-aarch64-unknown-linux-musl.tar.xz) | ARM64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-aarch64-unknown-linux-musl.tar.xz.sha256) |
| [worktrunk-x86_64-unknown-linux-musl.tar.xz](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-x86_64-unknown-linux-musl.tar.xz) | x64 MUSL Linux | [checksum](https://github.com/max-sixty/worktrunk/releases/download/v0.61.0/worktrunk-x86_64-unknown-linux-musl.tar.xz.sha256) |



### Install via Cargo

```sh
cargo install worktrunk && wt config shell install
```

### Install via Winget (Windows)

```sh
winget install max-sixty.worktrunk && git-wt config shell install
```

### Install via AUR (Arch Linux)

```sh
paru worktrunk-bin && wt config shell install
```
</pre>
  <p>View the full release notes at <a href="https://github.com/max-sixty/worktrunk/releases/tag/v0.61.0">https://github.com/max-sixty/worktrunk/releases/tag/v0.61.0</a>.</p>
</details>
<hr>

See merge request: Harmonybrew/homebrew-core!12090
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants