Module schema_cache 

--fdl-schema binary contract and per-command cache mechanics. Caches live at <cmd_dir>/.fdl/schema-cache/<cmd>.json; staleness is mtime-based against the command’s config AND, for a compile: true command, the sources its schema is compiled from. --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 every path that could change the schema — the command’s config file AND, for a binary that declares its own surface, the sources that surface is compiled from (see schema_source_refs). A cache older than any of them is stale. Users can also force-refresh.

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).

schema_source_refs

Every file whose edit could change a command’s --fdl-schema output.

write_cache

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