Install contributor Git hooks when dependencies are installed in a linked worktree

Start with scripts.prepare in package.json and compare its Git check with the worktree behavior described in the reproduction. Read lefthook.yml for the existing worktree-related configuration, then exercise the real preparation command using an isolated installer stub. Done means ordinary clones and fresh linked worktrees invoke Lefthook, non-Git directories remain no-ops, and regression coverage leaves real hooks untouched.

Problem

The root prepare script skips Lefthook in a Git linked worktree:

test -d .git && lefthook install || true

A linked worktree has a .git file, so the script exits successfully without invoking the installer. This matters when hooks have not already been installed in the repository's shared Git directory. An earlier installation in the primary checkout can mask the problem.

CONTRIBUTING.md promises automatic hook setup after bun install. The existing Lefthook configuration already accounts for worktree-specific Git environment variables.

Reproduction and evidence

Checked current main 86fa10ced4297bfd9f4fe67b6767afae7a07fd3c (0.8.69). Ran the exact package prepare command in three disposable fixtures with a stub lefthook executable that records its arguments. No real hooks were installed.

The linked worktree should invoke the same installer as an ordinary clone. A non-Git directory should remain a safe no-op.

Copyable reproduction

Run this from any directory with Git and Python 3 installed. It creates and automatically removes a disposable repository, ordinary clone, linked worktree, and non-Git control. lefthook is a logging stub placed first on the child process PATH; this never installs hooks in your actual repository.

python3 - <<'PY'
#!/usr/bin/env python3
"""Reproduce the current prepare guard without installing any real Git hooks."""
import json
import os
from pathlib import Path
import subprocess
import tempfile

with tempfile.TemporaryDirectory(prefix="hf-hook-guard-") as temporary:
    root = Path(temporary)
    seed = root / "seed"
    seed.mkdir()

    def git(*args, cwd=seed):
        return subprocess.run(
            ["git", *args], cwd=cwd, check=True, capture_output=True, text=True
        ).stdout.strip()

    git("init", "-q")
    (seed / "README").write_text("fixture\n")
    git("add", "README")
    git("-c", "user.name=Fixture", "-c", "[email protected]",
        "-c", "core.hooksPath=/dev/null", "commit", "-qm", "fixture")
    clone = root / "ordinary"
    linked = root / "linked"
    nongit = root / "non-git"
    git("clone", "-q", str(seed), str(clone))
    git("worktree", "add", "--detach", str(linked), "HEAD", cwd=clone)
    nongit.mkdir()
    stub_bin = root / "bin"
    stub_bin.mkdir()
    stub = stub_bin / "lefthook"
    stub.write_text('#!/bin/sh\nprintf "%s\\n" "$*" >> "$HF_HOOK_PROBE_LOG"\n')
    stub.chmod(0o755)
    rows = []
    for label, directory in [("ordinary", clone), ("linked", linked), ("non-git", nongit)]:
        log = root / (label + ".log")
        env = dict(os.environ, PATH=str(stub_bin) + os.pathsep + os.environ["PATH"],
                   HF_HOOK_PROBE_LOG=str(log))
        result = subprocess.run(
            ["sh", "-c", "test -d .git && lefthook install || true"],
            cwd=directory, env=env, check=True,
        )
        rows.append({"fixture": label, "prepare_exit": result.returncode,
                     "installer_calls": log.read_text().splitlines() if log.exists() else []})
    print(json.dumps(rows, indent=2))
PY

Expected current output: ordinary records ["install"]; linked and non-git record []. All three exit 0. The defect is the linked worktree's empty call list.

Scope

Make the preparation guard recognize supported Git worktrees. Preserve ordinary-clone behavior and non-Git handling. Do not change global Git configuration, replace unrelated user hooks, or rewrite the existing hook policy.

Start with package.json (scripts.prepare) and lefthook.yml. Prefer a minimal portable Git check rather than a new setup subsystem.

Acceptance criteria

• A disposable ordinary clone invokes Lefthook during preparation.
• A fresh linked worktree invokes it even when no hooks were installed earlier.
• A non-Git source directory skips setup cleanly.
• Regression coverage exercises the real preparation command with an isolated installer stub; it does not modify the developer's actual hooks.
• Existing commit validation remains unchanged.

Triage

Suggested difficulty: easy. The change is small, but tests must avoid accidentally relying on shared hooks installed by the ordinary-clone control.

No directly overlapping open issue or PR found in the refreshed inventory. Search again before claiming. Reviewer/mentor is still being arranged; this issue is not yet a newcomer invitation.