Module schema_cache 

--fdl-schema binary contract and per-command cache mechanics. Caches live at <cmd_dir>/.fdl/schema-cache/<cmd>.json with mtime + binary hash metadata for staleness detection. --fdl-schema binary contract: probe, validate, and cache.

A sub-command binary that opts into the contract exposes a single --fdl-schema flag printing a JSON schema describing its CLI surface. flodl-cli caches the output under <cmd_dir>/.fdl/schema-cache/<cmd>.json and prefers it over any inline YAML schema declared in fdl.yaml.

Cargo entries (entry: cargo run ...) are not auto-probed: invoking them forces a full compile, which is unacceptable latency for fdl --help. For those, users run fdl <cmd> --refresh-schema explicitly after a build.

Cache invalidation is mtime-based: the cache file’s mtime is compared against fdl.yml in the command dir. A cache older than its fdl.yml is considered stale. Users can also force-refresh.

See docs/design/run-config.md — “2. Option schemas and the --fdl-schema contract” — for the JSON shape.

Functions

cache_path

Resolve the cache file path for a given command dir and name.

is_cargo_entry

Heuristic: cargo entries compile-on-run, so they are never auto-probed. Probing must be explicit (fdl <cmd> --refresh-schema) for those.

is_stale

Consider a cache “stale” if it is older than the command’s fdl.yml (config changes), or older than a sentinel binary path when supplied.

probe

Probe a binary for its schema by running <entry> --fdl-schema via the shell and parsing stdout as JSON.

read_cache

Read a schema cache file, returning Some only if it parses cleanly and survives validation. Parse or validation errors are treated as “no cache” (the caller falls through to the inline/YAML schema).

write_cache

Serialize a schema to the cache file, creating parent dirs as needed.