[jdx]

Summary

• persist pklr package downloads under ~/.cache/pklr by default
• add HK_PKL_CACHE_DIR to override the persistent package cache location
• add HK_PKL_OFFLINE=1 for deterministic network-free Pkl evaluation

Motivation

hk caches its fully evaluated configuration, so unchanged hooks normally avoid package downloads. A config edit, hk upgrade, cache cleanup, or ephemeral hk cache still forces pklr to fetch the pinned package again. That can block local commits during a GitHub outage.

With the persistent pklr cache, a package downloaded during any prior evaluation remains available even after hk's resolved-config cache is invalidated. Offline mode fails immediately with the missing package URL and cache location instead of attempting the network.

This addresses discussion #1198.

Dependency status

pklr 1.4.0 was published by jdx/pklr#154, and Cargo.lock now resolves to that release. The manifest remains at the lowest compatible requirement, pklr = "1".

Validation

• mise run pkl:gen
• cargo check --locked
• cargo test --locked (254 passed)
• git diff --check

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

Summary by CodeRabbit

• New Features

  • Added HK_PKL_CACHE_DIR to configure the built-in package cache directory, defaulting to the platform’s standard cache location.
  • Added HK_PKL_OFFLINE to disable network access while continuing to use cached packages.
  • Offline mode supports common truthy environment values.

• Documentation

  • Documented the new environment variables and their usage.

---

Note

Low Risk
Scoped to pklr evaluation and env-driven cache/offline behavior; no auth or hook execution changes.

Overview
Built-in pklr now keeps downloaded Pkl packages on disk (default under the platform cache as pklr) and wires that through EvaluatorBuilder instead of the previous one-shot EvalOptions eval API. HK_PKL_CACHE_DIR overrides the cache path; HK_PKL_OFFLINE blocks network fetches while still using cached packages, with clear errors when a package is missing.

pklr is resolved to 1.4.0 in Cargo.lock for the new cache/offline support. Docs add both variables and note they are read from the environment before hk.pkl is evaluated (not configurable inside hk.pkl).

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 7f201a3e-b332-45af-b939-746f92f24936

📥 Commits

Reviewing files that changed from the base of the PR and between 1df62cc and 449c2bf.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (1)

• docs/environment_variables.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/environment_variables.md

---

📝 Walkthrough

Walkthrough

The change adds HK_PKL_CACHE_DIR and HK_PKL_OFFLINE, documents both variables, and passes their values to pklr::EvaluatorBuilder during run_pklr.

Changes

PKL cache and offline configuration

Layer / File(s)	Summary
Environment settings and documentation src/env.rs, docs/environment_variables.md	Adds the cache directory setting with platform-based fallbacks. Adds the offline setting with truthy-value parsing. Documents both settings.
pklr evaluation wiring src/config.rs	Configures pklr::EvaluatorBuilder with the cache directory and offline mode, alongside the existing HTTP client and rewrite rules.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 449c2

This PR adds persistent and optional offline package caching for Pkl evaluation; no actionable merge-blocking risk remains based on the supplied evidence.

Poem

I’m a rabbit tuning caches bright,
PKL packages rest just right.
Offline paths now hold their ground,
Clear settings pass around.
Hop, hop—evaluation runs!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: persistent pklr package caching and offline evaluation.

---

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

The PR adds a persistent package cache and offline evaluation mode to the built-in pklr backend.

• Configures pklr 1.4 through EvaluatorBuilder with cache and offline settings.
• Adds HK_PKL_CACHE_DIR and HK_PKL_OFFLINE.
• Documents platform-specific cache defaults and offline behavior.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains, and the previously reported platform-dependent cache-path documentation issue has been fixed.

Important Files Changed

Filename	Overview
src/config.rs	Migrates embedded Pkl evaluation to EvaluatorBuilder and supplies the persistent cache directory and offline setting.
src/env.rs	Adds lazily parsed environment settings for the pklr cache location and offline mode.
docs/environment_variables.md	Documents the new settings and corrects the previously reported omission by listing platform-specific cache defaults.
Cargo.lock	Updates the resolved pklr dependency from 1.3.0 to 1.4.0.

_{Reviews (4): Last reviewed commit: "docs: clarify pkl cache directory defaul..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/environment_variables.md`:
- Line 207: Update the HK_PKL_CACHE_DIR default documentation to describe the
platform-specific directory returned by dirs::cache_dir(), including the Linux
example ~/.cache/pklr, and retain the fallback path only as a fallback rather
than the unconditional default.

In `@src/config.rs`:
- Around line 748-749: Update the EvalOptions construction around
package_cache_dir and offline to match the locked pklr 1.3.0 API: either add a
reproducible dependency patch that provides these fields or remove/defer this
wiring until a compatible pklr release is available. Ensure the project compiles
with --locked without referencing unsupported EvalOptions fields.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: acb392b2-5714-405d-a59c-f6f2ffd28ac2

📥 Commits

Reviewing files that changed from the base of the PR and between c9cfc1f and a7a399e.

📒 Files selected for processing (3)

• docs/environment_variables.md
• src/config.rs
• src/env.rs

[github-actions]

Instruction counts

The comparison never ran — an earlier step failed.

_{1df62cc09d35 vs `` · measured on the runner, not pushed to the history.}

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/​pklr@​1.3.0 ⏵ 1.4.0	-1

View full report