ReadonlycachedReadonlydirtyMost recent error from a refreshFromGist() attempt, or null when the
last attempt succeeded or was skipped by the throttle. Lets callers
(StateManager) distinguish "throttled, nothing new to see" from "fetch
failed, you're now operating on stale state" without changing the
existing boolean return contract (#1193).
Bootstrap the Gist store: locate or create the backing Gist, populate the in-memory cache, and write the local cache file.
Bootstrap with migration from an existing local state. If a Gist already exists (found via local ID or search), uses it — no migration needed. If no Gist exists, creates one seeded with the provided existingState instead of a fresh state.
BootstrapResult extended with migrated: true if a new Gist was created from local state
Read a freeform document from the in-memory cache. Returns null if the file has not been loaded (or does not exist in the Gist). Synchronous — all Gist contents are loaded into memory at bootstrap.
Return the resolved Gist ID (available after bootstrap).
Return all filenames in the in-memory cache whose names start with prefix.
Useful for listing all guidelines files (e.g. prefix guidelines--).
Mark a file as dirty so it will be included in the next push() call.
Push all dirty files to the backing Gist.
Behavior:
If-Match header (#1510). The
Gist PATCH endpoint rejects conditional headers on unsafe methods
with HTTP 400, so the server cannot enforce optimistic concurrency.state.json is among the dirty files, push() re-reads the Gist
first and compares the remote state.json against the baseline
captured at our last fetch. If it moved under us, another machine
wrote concurrently and push() throws GistConcurrencyError
instead of clobbering — preserving the StateManager compare-and-swap
contract (#1235). The local mutation stays in memory so the caller
can refreshFromGist() and reapply. There is a small unavoidable
TOCTOU window between the re-read and the write (the Gist API offers
no atomic conditional write), but it is far narrower than the
last-fetch-to-push window the dropped If-Match covered.files parameter is a partial update, so a freeform-only push needs
no re-read and cannot clobber another file.false.Returns true on success (or when there is nothing to push).
Returns false if a push fails on both attempts.
Throws GistConcurrencyError when state.json moved remotely
since our last fetch (#1235, #1510).
Throws GistCorruptError when the pre-write re-read finds a
corrupt remote (so the caller does not retry against it).
Throws if the Gist ID has not been resolved yet (bootstrap not called).
Re-fetch the Gist and update the in-memory cache. Throttled to at most once per 30 seconds — ATTEMPTS, not just successes: a failed fetch stamps the throttle too (#1443), so an outage does not turn every SPA poll into an immediate full re-fetch.
Returns a discriminated union so callers can tell apart the four outcomes that previously collapsed into a single boolean (#1209 L9):
{ status: 'refreshed' } — fresh data loaded successfully.{ status: 'no-gist' } — store not in Gist mode (e.g. degraded).{ status: 'throttled', sinceLastMs } — within the 30s throttle
(skipped when options.force is set).{ status: 'error', error } — fetch attempt failed.Write a freeform document into the in-memory cache and mark it dirty
so it will be included in the next push() call.
Stage new state JSON for the next push(). Updates the in-memory cache
for state.json and marks it dirty.
Gist-backed state store with in-memory file cache and local write-through.