refactor(config)!: remove deprecated v1 interfaces

[jdx]

Summary

• accept Pkl project configs only and return targeted v2 migration errors for removed raw formats and hkrc entry points
• remove UserConfig.pkl, Types.pkl, deprecated Regex/BOM aliases, and the hk generate compatibility alias
• retain XDG config.pkl and hk.local.pkl, update generated docs, and add a complete v1-to-v2 migration guide

Stack

• Depends on feat(hook)!: make staging contextual #1256
• feat(hook)!: make staging contextual #1256 depends on feat(config)!: add shared top-level steps #1255
• feat(config)!: add shared top-level steps #1255 depends on feat(builtins)!: expose configurable builtin factories #1253

GitHub Issues are disabled for this repository, so the PR stack serves as the v2 rollout tracker.

Verification

• mise run test:cargo (287 passed)
• focused migration, hkrc, regex, staging-filter, and workspace Bats suites on libgit2 and shell Git backends
• full Bats run: all project integration tests passed; builtin meta-suite remains blocked by existing jq/ktlint tool-stub failures and one pinact_v3 tool failure
• MISE_HK_VERSION=1.56.1 MISE_SHELLCHECK_VERSION=0.11.0 ./target/debug/hk check --all
• cargo fmt --check
• Pkl and Taplo format checks

AI-assisted — Tool: Codex; model: unavailable/unavailable; version: unavailable.

---

Note

High Risk
Breaking removal of multiple config formats and global config discovery affects every hk run; mis-migrated users will fail until they move to Pkl and XDG paths.

Overview
hk v2 drops legacy configuration paths and CLI compatibility; only Pkl project configs (hk.pkl) are loaded. hk.toml/yaml/json, CWD/home .hkrc.pkl, --hkrc, UserConfig.pkl, Types.pkl, and deprecated Config.Regex / byte-order-marker builtin aliases are removed. hk generate is rejected early with a pointer to hk init.

Global settings now come solely from ~/.config/hk/config.pkl (merged with project config using existing project-wins rules). UserConfig merge logic and runtime deprecation warnings are deleted; Pkl eval failures and leftover files instead return targeted migration hints (e.g. environment → env, Regex built-in).

pkl/Config.pkl drops the deprecated Regex helper and makes several list settings optional instead of default-empty. Docs add migration-v2, refresh configuration precedence text, and regenerate CLI usage without --hkrc / generate. Integration tests shift from .hkrc.pkl to XDG config and assert v2 rejection paths.

^{Reviewed by Cursor Bugbot for commit 0070b96. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 94422f95-18fe-400e-846a-bd283dc185d5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR removes deprecated v1 configuration and CLI interfaces while adding targeted migration guidance for affected users.

• Restricts project configuration to Pkl and replaces legacy hkrc handling with XDG config.pkl.
• Removes deprecated Pkl modules, aliases, builtins, and the hk generate compatibility alias.
• Updates configuration merging, documentation, generated CLI references, and migration coverage.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains.

The previously reported environment-precedence issue is fixed: global configuration initialization no longer exports conflicting values, while the merge exports global-only values and leaves existing project values unchanged.

Important Files Changed

Filename	Overview
src/config.rs	Replaces legacy format and hkrc compatibility paths with v2 migration errors while preserving project-wins environment merging.
src/cli/mod.rs	Removes deprecated CLI registrations and detects removed interfaces early to provide targeted errors.
pkl/Config.pkl	Removes deprecated Regex compatibility and makes list-valued configuration properties optional for layered merging.
scripts/gen_builtins.py	Stops generating deprecated byte-order-marker aliases.
docs/migration-v2.md	Documents replacements for removed v1 configuration, builtin, staging, and command interfaces.

_{Reviews (21): Last reviewed commit: "perf(config): keep v1 tombstones out of ..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
builtins	████████████████▁	1,989,871 → 1,537,066	-22.76%	2.92 → 1.76ms	-39.58%
check	—	—	—	21.50 → 20.66ms	-3.92%
usage	██████▇█▇▇▇█████▁	4,650,086 → 4,611,056	-0.84%	3.16 → 3.49ms	+10.27%
validate	—	—	—	5.48 → 5.13ms	-6.37%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{0070b96dfe31 vs a15fcdfb197f · measured on the runner, not pushed to the history.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f197252. Configure here.}