docs(scratch): document scratch caches — driver, CLI, config, Go/OCI callers - #108
Merged
Conversation
… Go/OCI callers Scratch caches (driver = "scratch") have been buildable and in production use in the go/oci plugins for several merged PRs (heph#403, #434, #435) but had never reached these docs. hephbuild/heph@12b6391 (#437) — the compile/module/ OCI-blob cache retrofit, plus making `path` optional — was the trigger to close that gap, so this covers the whole feature as it stands on master rather than just the incremental diff. - New concepts/scratch.md: the contract, the driver's Starlark fields, access/version semantics, --no-scratch auditing, remote push/pull, the `heph tool scratch` CLI, and the output/mount pitfall. - reference/configuration.md: the `scratch:` (scope/restoreScopes/seedOnFork) block. - plugins/go.md: the automatic GOCACHE/GOMODCACHE scratch caches and heph.go.gocache_addr(). - plugins/oci.md: oci_pull's shared registry blob cache. - Mirrored the additions into the heph-expert and heph-go Claude Code plugin reference twins per the reference-drift rule. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01P9GCJXF5CCzPbwfnr8xw9y
raphaelvigee
enabled auto-merge (squash)
September 3, 2026 08:21
⚡ Cloudflare Pages preview
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Scratch caches (
driver = "scratch") have been buildable and in production use by the Go and OCI plugins for several merged PRs (heph#403, #434, #435), but had never reached these docs — adocs/SCRATCH.mdsearch of this site turned up nothing at all. hephbuild/heph@12b6391 (#437 — the compile/module/OCI-blob cache retrofit, plus making the declaration'spathfield optional) is what triggered this pass, so it documents the whole feature as it stands onheph'smaster, not just this commit's incremental diff.website/docs/concepts/scratch.md— the contract, thedriver = "scratch"Starlark fields (path,env,access,version,remote,max_size), choosingaccess, portability viaversion, auditing with--no-scratch, publishing/pulling through the remote cache, theheph tool scratch {ls,head,path,rm,push,pull}CLI plusheph tool gc --scratch-max-size/--scratch-max-age-days, and the output/mounted-scratch pitfall. Registered insidebars.ts.website/docs/reference/configuration.md— newscratch:config block (scope,restoreScopes,seedOnFork).website/docs/plugins/go.md— new "Build and module caches" section: the automatic per-moduleGOCACHEand sharedGOMODCACHE, andheph.go.gocache_addr()for sharing them from hand-written targets.website/docs/plugins/oci.md—oci_pull's shared registry blob cache.plugins/heph-expert/skills/heph/references/{concepts,configuration}.md,plugins/heph-go/skills/heph-go/references/go-plugin.md) per this repo's reference-drift rule.Every field, CLI subcommand, and config key here was checked against the current source in
hephbuild/hephonmaster(thepluginscratch/gocache/platform.rsdrivers,src/commands/tool/scratch.rs,crates/config/src/config_yaml.rs) rather than taken from the PR description alone — one behavior claimed in the PR body (a new parse-time guard rejecting an output glob that reaches a scratch mount) didn't match what the current code and its own tests actually do, so the docs describe the verified behavior (rejected when heph packs the output, naming the mount) instead.Triggered by
hephbuild/heph#437 — perf(scratch): compile, module and OCI blob caches — and outputs can no longer collect one (commit
12b6391f674de9ac9949bf7de1ad49d58a48f783)Test plan
hephbuild/heph@12b6391(crates/builtins/src/pluginscratch/mod.rs,crates/config/src/config_yaml.rs,src/commands/tool/scratch.rs,crates/plugin-go/src/plugingo/gocache.rs,crates/plugin-oci/src/pluginoci/platform.rs).🤖 Generated with Claude Code
https://claude.ai/code/session_01P9GCJXF5CCzPbwfnr8xw9y
Generated by Claude Code