Skip to content

refactor(hooks): derive the hook preview from the execution path - #3635

Merged
max-sixty merged 2 commits into
mainfrom
hook-preview-shared-context
Jul 28, 2026
Merged

max-sixty merged 2 commits into
mainfrom
hook-preview-shared-context

Conversation

@max-sixty

Copy link
Copy Markdown
Owner

wt hook show --expanded rebuilt the hook pipeline's template context by hand in expand_command_template, duplicating what prepare_steps already does for what actually runs: the same build_hook_context call, the same hook_type and hook_name inserts, the same args default, the same POSIX escape mode. Two copies of one rule, so the preview drifted from the executed command whenever the execution path gained a context key, with nothing to catch it.

The listing now prepares its commands through prepare_steps itself (hook_command_rows in hook_commands.rs) and renders them through render_template_preview, the renderer wt hook <type> --dry-run already used. prepare_steps is the sole producer of hook command contexts, so a key added there reaches both with no second edit.

The args divergence

The old preview inserted args = "[]" unconditionally; prepare_steps defaults it only when unset, because manual wt hook <type> supplies real args upstream via extra_vars. The shared path keeps the conditional default and the listing simply does not supply args. The values coincide (a listing has no CLI args to forward, which is exactly what the default encodes), and keeping the conditional form means the rule stays written once, in the place that has a caller who needs the other branch.

Where the syntax check went

prepare_steps used to reject an unparsable template, so a pipeline that could not render in full never started. A listing wants the opposite: wt hook show is what you run when your hooks are broken, so it annotates the bad template in place and shows the rest.

That check is an execution policy rather than part of building a command, so it moved out of prepare_steps into validate_pipeline_syntax, called by the two funnels every hook-running path goes through: prepare_and_check (foreground, background, dry-run, filtered) and render_planned (the plan-backed hooks behind execute_planned_hook and register_planned). Both are mutation-verified: removing either call fails a test.

A newtype that made forgetting the gate a compile error would be stronger, but it threads a wrapper through SourcedStep, ForegroundStep, and the background pipeline spec for a guard whose failure mode is degraded fail-fast rather than incorrectness (a syntax error still surfaces when its step renders).

User-visible changes

Preview expansion errors now name the hook (Failed to expand project:lint: ...) instead of the generic hook preview.

A template referencing vars.* renders raw in --expanded, matching --dry-run, where before it resolved against git config at preview time. Raw is the honest preview: those values resolve when the step runs, and an earlier step in the pipeline may write them.

Tests

test_hook_show_expanded_matches_dry_run pins the listing and the dry-run to the same rendering of hook_type, hook_name, and args. test_foreground_pipeline_syntax_error_aborts_before_first_step pins the relocated gate; it runs through wt merge's pre-commit hooks because wt hook <type> cannot reach it (the CLI pre-parses every template for shorthand-argument routing and errors first).

Also folded in: adding source: HookSource to the listing renderer left approval_context: Option<(&Approvals, Option<&str>)> encoding the same user-vs-project discriminator, so both sites now call one needs_approval.

This was written by Claude Code on behalf of max

max-sixty and others added 2 commits July 28, 2026 13:28
`wt hook show --expanded` rebuilt the pipeline template context by hand,
duplicating what `prepare_steps` already does. It now prepares its
commands through `prepare_steps` itself, so a context key the execution
path gains reaches the preview with no second edit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Adding `source` to the listing renderer left `approval_context` encoding
the same user-vs-project discriminator, so both sites now call one
`needs_approval`. Also pins the relocated syntax gate with a test that
reaches it — `wt hook <type>` cannot, because the CLI pre-parses every
template for shorthand routing and errors first.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@max-sixty
max-sixty marked this pull request as ready for review July 28, 2026 22:16
@max-sixty
max-sixty merged commit 4888d52 into main Jul 28, 2026
40 checks passed
@max-sixty
max-sixty deleted the hook-preview-shared-context branch July 28, 2026 22:25
max-sixty added a commit that referenced this pull request Jul 28, 2026
Follow-up to #3635, from two reviews that landed after it merged.

## The `vars.*` preview was worse than #3635 claimed

`render_template_preview` short-circuits on
`template_references_var(template, "vars")`, returning the raw template.
So one `vars.` token disabled expansion for the entire command:

```
pre-commit = "deploy --branch={{ branch }} --repo={{ repo }} --env={{ vars.env }}"

before:  deploy --branch={{ branch }} --repo={{ repo }} --env={{ vars.env }}
after:   deploy --branch=main --repo=repo --env={{ vars.env }}
```

#3635 described this as "a `vars.*` template renders raw", which is true
but understates it: `{{ branch }}` and `{{ repo }}` stopped expanding
too, in a command whose whole job is to show the expansion. That
short-circuit predates #3635 and has been degrading `wt hook <type>
--dry-run` the same way; #3635 only extended it to `wt hook show
--expanded`.

The fix is at the source rather than at either caller. A preview now
injects a stand-in object for `vars` that renders each reference back as
itself, nested access included (`{{ vars.config.port }}` round-trips),
while every other variable expands normally. `VarsMode::Resolve` keeps
execution reading real values from git config; only previews pass
`VarsMode::Literal`. A preview also no longer spawns the git read that
resolving `vars` required.

`vars.*` stays literal on purpose: those values are read when the step
runs, after an earlier step in the pipeline may have written them, so a
value resolved at preview time can differ from the one the run uses.

Nothing covered this, which is why the suite stayed green through the
regression. `test_hook_show_expanded_matches_dry_run` now sets a var and
asserts the listing and the dry-run both leave it alone while expanding
`{{ branch }}` beside it.

## The syntax gate is a type error now

#3635 moved the template syntax check out of `prepare_steps` into a free
`validate_pipeline_syntax` that both execution funnels had to remember
to call. `prepare_steps` now returns a `PreparedPipeline` the caller
must resolve: `.validated()` for the paths that run hooks,
`.into_unvalidated()` for the listing, which annotates a broken template
in place rather than blanking itself. Forgetting is a compile error, the
same property `ApprovedHookPlan` gives hook approval.

## Smaller items

Four cross-references went stale when the syntax check moved:
`PreparedCommand.template`, `validate_template_syntax`, the `switch.rs`
skip comment, and `HOOK_INFRASTRUCTURE_VARS` (which still named two
deleted functions). The `--expanded` behavior is now documented in the
sentence that already owns `{{ vars.<key> }}` semantics, with its three
generated mirrors regenerated.

`PreparedStep::commands()` replaces two hand-rolled matches in
`hooks.rs`. `default_branch` moves inside
`build_manual_hook_template_vars` — only the commit-hook arm reads it,
and resolving it can cost a `git ls-remote` on a fresh clone, so the
other eight hook types no longer pay for it. The listing carries its
expansion state in an `Option<String>` instead of re-deriving "was this
expanded?" from whether a context exists.

> _This was written by Claude Code on behalf of max_

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
max-sixty pushed a commit that referenced this pull request Aug 7, 2026
…#3765)

Nightly sweep finding: two `.config/clawpatch/features/*.json`
entrypoints name symbols that no longer exist.

**`feat_custom_template_expansion.json`.** `expand_command_template` was
deleted by #3635 ("derive the hook preview from the execution path"),
which folded the preview render into `render_template_preview` in
`src/commands/command_executor.rs` and left `expand_template` in
`src/config/expansion.rs` as the single runtime render. The feature file
kept pointing at the old name, so the one thing it exists to do — send a
reader to the code that renders a project-supplied template before the
approval gate sees it — lands nowhere.

- **Entrypoint** → `src/config/expansion.rs::expand_template`. The
module doc calls it "a single generic function" for template rendering,
and it's what the feature's own summary is about ("expansion happens
before the approval gate sees the final string").
- **`ownedFiles` reordered and re-reasoned.** `expansion.rs` moves first
and its reason now names the render functions. `command_executor.rs` is
added — that's where #3635 put `render_template_preview` and the
foreground step pipeline, so the file the code moved *into* was missing
from a file list that still described where it came from.
`hook_commands.rs` stays, with its reason updated to what it actually
holds now (`run_hook`, the `hook show --expanded` rows).

**`feat_custom_switch_resolve.json`.** Entrypoint `handle_switch` →
`handle_switch_command`. The function was renamed when #3049 moved
switch/remove orchestration out of `main.rs`; the definition today is
`pub fn handle_switch_command` at `src/commands/worktree/switch.rs`.

This second one is why the sweep's original audit reported only one
stale symbol: it grepped each `entrypoints[].symbol` as a plain
substring, and `handle_switch` matches inside `handle_switch_command`
(and `handle_switch_output`, `handle_switch_created_output`, …), so a
renamed symbol whose new name merely extends the old one reads as
present. Re-run anchored on a definition —
`\b(fn|struct|enum|trait|type|const|static|mod)\s+<symbol>\b` inside the
declared `path` — all 14 features now resolve, and no other entrypoint
has this shape.

Following the convention of the last edit to this directory (3554f49,
which fixed `interrupt_exit_code` → `interrupt_signal` in the
signal-handling feature), symbol names are corrected in place and
`updatedAt` is left alone.

No test accompanies this — nothing in the suite reads
`.config/clawpatch/`, which is why both references went stale silently.
A sync test is conceivable, but it would be a new check on a
hand-authored threat-model index whose schema this repo doesn't own; I'd
rather flag the idea than build it unasked. If one is ever added, it
should anchor on the definition, not a substring grep, for the reason
above.

---------

Co-authored-by: worktrunk-bot <254187624+worktrunk-bot@users.noreply.github.com>
social4hyq pushed a commit to social4hyq/homebrew-core that referenced this pull request Sep 20, 2026
worktrunk 0.70.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 step prune` removes worktrees far faster**: Each removal ran a serial chain of ~17 git subprocesses under the scan write lock, re-preparing a plan the scan had already computed and re-stating the worktree right after the fsmonitor daemon stop. The chain is now one check per guarantee, reusing the scan-time plan, and removals run concurrently on the scan lock's read side — the write side is kept for the candidates that need it (hook-bearing, `--foreground`, metadata-pruning, and the current worktree). The documented rust-scale live prune of 24 candidates goes from ~12 s to ~0.6 s wall, and the `prune_e2e/live` benchmark from ~620 ms to ~400 ms. ([#3617](max-sixty/worktrunk#3617), [#3631](max-sixty/worktrunk#3631))

- **`wt step prune --format=json` is ordered, and a failed removal aborts the rest**: Live JSON output is now sorted by scan index, matching `--dry-run`, with the current worktree last. The first failing removal drains the remaining queue unexecuted, matching the serial loop it replaced; in-flight removals complete. ([#3631](max-sixty/worktrunk#3631))

- **A worktree can be named by its path wherever a branch is accepted**: Every argument that takes a branch now also accepts the worktree's own path, resolved after the branch so a directory never shadows a branch sharing its name. A path names what a branch cannot — a detached worktree, or one of two checkouts of the same branch. Relative paths resolve against `-C` and a leading `~` against the home directory, so a path worktrunk printed can be pasted back. [Docs](https://worktrunk.dev/switch/#naming-a-worktree) ([#3607](max-sixty/worktrunk#3607))

- **`wt list` flags a branch checked out in more than one worktree**: Such a branch resolves to whichever worktree git lists first, so every worktree on it now carries `⚑` — `worktree.state` `"duplicate_branch"` in schema 1, a `worktree.duplicate_branch` boolean in schema 2. The flag makes the ambiguity visible in the listing; resolving such a branch from any command warns separately and names a duplicate to drop. ([#3480](max-sixty/worktrunk#3480), [#3606](max-sixty/worktrunk#3606))

- **`wt switch --execute` computes only the template variables its command names**: The switch path built every variable the template context could hold before rendering; it now resolves just the ones the command references. On a clone with no `origin/HEAD` and no cached default branch, that removes a `git ls-remote` the command never asked for — 13 subprocesses and one remote query down to 8 and none. ([#3628](max-sixty/worktrunk#3628))

### Fixed

- **A branch checked out in a second worktree is retained on removal, `-D` included**: `wt remove` and `wt step prune` now act on the worktree named rather than the branch's first checkout, and all three of `wt remove`, `wt step prune`, and `wt merge` keep the branch while another worktree still has it out — deleting the ref would leave that worktree unable to resolve `HEAD`, which is why `git branch -d` refuses the same delete. The retention is reported and names the surviving checkout rather than passing silently. ([#3533](max-sixty/worktrunk#3533))

- **Removal reports what it took, not what it selected**: A removal's summary and JSON described the plan, so a worktree candidate whose branch was retained still counted as `✓ Pruned 1 branch`, and `wt remove --format=json` reported `"branch_deleted": true` beside a stderr line saying the branch was kept. Execution now returns the branch's fate; `wt step prune` counts executed outcomes (`--dry-run` included), both JSON payloads gained `branch_deleted`, and a declined orphan deletion drops out of the removed list rather than being reported as removed. ([#3633](max-sixty/worktrunk#3633), [#3637](max-sixty/worktrunk#3637))

- **Hook previews expand every variable except `vars.*`**: One `vars.` token disabled expansion for the whole command, so `wt hook show --expanded` and `wt hook <type> --dry-run` printed `{{ branch }}` and `{{ repo }}` raw in a listing whose job is to show the expansion. A preview now substitutes a stand-in that renders each `vars.*` reference back as itself, nested access included, while every other variable expands — and no longer spawns the git read that resolving `vars` required. The listing is also derived from the execution path itself, so a context key added there reaches the preview with no second edit. `wt config alias dry-run` shares the renderer, so its help text — which still described the all-or-nothing behavior — was corrected to match. ([#3635](max-sixty/worktrunk#3635), [#3638](max-sixty/worktrunk#3638), [#3639](max-sixty/worktrunk#3639))

- **`wt hook show` no longer prints a bare heading for an empty command list**: A hook type declared as `post-switch = []` has a config entry but no commands, and the section decided it had printed something from the entry rather than from the rows — so it emitted its heading and stopped, and the `(none configured)` line never appeared. Both the user and project sections carried the bug, since the loop and the fallback were duplicated; they now share one renderer that reports whether it wrote any rows. The execution path was already correct: an empty list announces nothing and is omitted from JSON. ([#3641](max-sixty/worktrunk#3641))

- **`wt config shell install` reclaims its own legacy wrapper paths**: Fish sources `conf.d` at startup, so a stale `conf.d/{cmd}.fish` was already loaded by the time fish would autoload the `functions/{cmd}.fish` the install had just written — the old definition won and the new wrapper never loaded. Install decided ownership by reading the file, and left anything unrecognized in place. Ownership now comes from the path: `conf.d/{cmd}.fish` and the stranded nushell `{cmd}.nu` candidates are paths worktrunk computes for the command being installed, so it takes them back whole, unread. Only that exact filename is touched — a neighbour under another name is not worktrunk's — and each removal is reported. `wt config shell uninstall` still reads the header, because it takes no `--cmd` and so cannot know the name; it prompts and previews every file first. (Breaking: install now removes a file at those exact paths regardless of its contents.) ([#3602](max-sixty/worktrunk#3602))

- **Command timeouts actually bound wall-clock, and a default branch guessed while the remote was unreachable isn't cached**: A timeout killed only the direct child, so a surviving grandchild held the output pipe open and the call ran on regardless — a 3 s bound measured at 120 s. A timed command now runs in its own process group and the whole tree is torn down on expiry, which fixes every existing bound including the fsmonitor and reap probes. On top of that, nothing in git bounds `git ls-remote` (an unreachable host costs ~127 s per address on Linux), so default-branch detection abandons the query after 10 s and falls back to local inference — without caching the result, so an outage can't make an inferred default branch permanent. (Breaking: because a timed command gets its own process group, Ctrl-C no longer reaches it; the command waits out the remaining bound.) ([#3603](max-sixty/worktrunk#3603))

- **`wt step relocate` no longer strands a worktree in its staging directory**: When worktree A's target was held by worktree B, and B was itself blocked by a non-worktree path without `--clobber`, the dependency loop read the stall as a cycle, temp-moved A into `.git/wt/staging/relocate/`, then failed moving it into the still-occupied target — leaving A at neither its original nor its expected path. A worktree blocked by an immovable occupant is now skipped. ([#3530](max-sixty/worktrunk#3530))

- **Forge CLI failures are classified by response shape, not by the tool's prose**: `tea api` copies the response body to stdout and exits 0, so an HTTP error never tripped the exit-code gate — a Gitea `APIError` body deserialized into `{state: "", total_count: 0}`, indistinguishable from a commit with no CI statuses, while the PR-list path blamed an API change for what was an API error. Failures from `gh`, `glab`, and `tea` are now keyed on the response envelope, and a non-zero exit keeps meaning the tool itself failed; the CLI's own error text is forwarded rather than reworded, so a bad token surfaces as `gh: Bad credentials (HTTP 401)` instead of a suggestion to re-authenticate. `wt config show --full` reports the Azure DevOps CLI extension alongside the other forge tools. ([#3595](max-sixty/worktrunk#3595), [#3597](max-sixty/worktrunk#3597), [#3605](max-sixty/worktrunk#3605))

- **`wt config plugins claude install-statusline` no longer mistakes another tool's statusline for its own**: The check for an existing worktrunk statusline matched the bare substring `wt `, which an unrelated command like `newt status` satisfies — so `wt config show` reported a foreign statusline as worktrunk's, and the installer early-returned "already configured" and refused to install. It now matches the adjacent `list statusline` token pair, so it works whether the binary is `wt`, `git-wt`, or an absolute path. ([#3595](max-sixty/worktrunk#3595))

- **`[list] task-timeout-ms` is removed**: The per-command bound is gone; `[list] timeout-ms` bounds the whole collect phase. A config that still sets it warns, and `wt config update` strips the key — i

See merge request: Harmonybrew/homebrew-core!15439
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