Surface cache controls in CLI and defaults #21

New issue

Open

opened 2025-11-19 13:21:17 +00:00 by glenux · 2 comments

glenux commented

2025-11-19 13:21:17 +00:00

Owner

title: Surface cache controls in CLI and defaults
description: Provide explicit CLI options/docs for cache usage and ensure sensible defaults, since users report cache never used (likely because enable_cache defaults to false and isn't exposed in CLI).
current_situation:

DocMachine::Build::Config sets enable_cache default true in code but CLI never exposes a flag to disable/enable; users cannot tell whether caching is active.
_pull_image logic effectively disables cache reuse (see task a95c1b2), but even with fixes we need explicit commands/flags to control behaviour.
Documentation/--help lacks information on caching directories, environment overrides, or how to refresh the cache.
expected_outcome:
CLI option (e.g., --cache/--no-cache) clearly toggles caching; help text documents XDG_CACHE_HOME usage.
Default behaviour ensures cache is used on subsequent runs without additional flags.
Docs/README updated with instructions and troubleshooting steps for cached images.
technical_details:
Add CLI flag(s) to DocMachine::Build::Cli and wire them to config.enable_cache or future cache policies.
Provide command (or option) to force refresh (skip cache) when needed.
Document caching in README/docs, including location and how to clean it.

--- title: Surface cache controls in CLI and defaults description: Provide explicit CLI options/docs for cache usage and ensure sensible defaults, since users report cache never used (likely because `enable_cache` defaults to false and isn't exposed in CLI). current_situation: - `DocMachine::Build::Config` sets `enable_cache` default true in code but CLI never exposes a flag to disable/enable; users cannot tell whether caching is active. - `_pull_image` logic effectively disables cache reuse (see task a95c1b2), but even with fixes we need explicit commands/flags to control behaviour. - Documentation/`--help` lacks information on caching directories, environment overrides, or how to refresh the cache. expected_outcome: - CLI option (e.g., `--cache/--no-cache`) clearly toggles caching; help text documents `XDG_CACHE_HOME` usage. - Default behaviour ensures cache is used on subsequent runs without additional flags. - Docs/README updated with instructions and troubleshooting steps for cached images. technical_details: - Add CLI flag(s) to `DocMachine::Build::Cli` and wire them to `config.enable_cache` or future cache policies. - Provide command (or option) to force refresh (skip cache) when needed. - Document caching in README/docs, including location and how to clean it. ---

glenux changed title from ~~d6a41fc Surface cache controls in CLI and defaults~~ to Surface cache controls in CLI and defaults

2025-11-19 13:26:22 +00:00

glenux added this to the By Status project

2025-11-19 18:02:48 +00:00

glenux commented

2026-01-20 17:36:28 +00:00

Author

Owner

En investiguant le code actuel, la raison principale du « cache jamais utilise » est que enable_cache est desactive par defaut et n'est pas activable via la CLI.

src/build/config.cr: property enable_cache : Bool = false
src/build/cli.cr: seule option --no-cache qui force false (pas de --cache/--enable-cache).
src/build/run.cr#_pull_image: quand cache_enabled=false => docker pull systematique.

A noter: la section current_situation de ce ticket mentionne un defaut true, mais dans HEAD (8da1820) c'est false. => a mettre a jour dans le ticket ou ajuster l'implementation selon la decision UX (defaut true vs flag explicite).

En investiguant le code actuel, la raison principale du « cache jamais utilise » est que `enable_cache` est *desactive par defaut* et n'est pas activable via la CLI. - `src/build/config.cr`: `property enable_cache : Bool = false` - `src/build/cli.cr`: seule option `--no-cache` qui force `false` (pas de `--cache`/`--enable-cache`). - `src/build/run.cr#_pull_image`: quand `cache_enabled=false` => `docker pull` systematique. A noter: la section `current_situation` de ce ticket mentionne un defaut `true`, mais dans HEAD (8da1820) c'est `false`. => a mettre a jour dans le ticket ou ajuster l'implementation selon la decision UX (defaut true vs flag explicite).

glenux referenced this issue

2026-01-20 17:36:32 +00:00

Save docmachine image in local cache #2

glenux referenced this issue

2026-01-20 17:36:41 +00:00

Cache Docker: utiliser un cache par image/tag + metadata/digest (eviter image.tar global) #28

glenux referenced this issue

2026-01-20 17:36:50 +00:00

Cache Docker: ajouter mode offline/cache-only + controler le pull (docker run --pull=never) #29

glenux added a new dependency

2026-01-20 17:36:54 +00:00

#29 Cache Docker: ajouter mode offline/cache-only + controler le pull (docker run --pull=never)

glenux added a new dependency

2026-01-20 17:36:54 +00:00

#28 Cache Docker: utiliser un cache par image/tag + metadata/digest (eviter image.tar global)

glenux commented

2026-01-20 18:12:05 +00:00

Author

Owner

Correction implementee localement (non-pushee):

src/build/config.cr: enable_cache passe a true par defaut.
src/build/cli.cr: ajout du flag --cache + maintien de --no-cache.
README.md: doc rapide sur l'emplacement du cache (XDG) + commande --no-cache.
spec/build/cli_spec.cr: test pour verifier que docmachine build --help expose bien --cache et --no-cache.

crystal spec --error-trace OK (23 examples).

Correction implementee localement (non-pushee): - `src/build/config.cr`: `enable_cache` passe a `true` par defaut. - `src/build/cli.cr`: ajout du flag `--cache` + maintien de `--no-cache`. - `README.md`: doc rapide sur l'emplacement du cache (XDG) + commande `--no-cache`. - `spec/build/cli_spec.cr`: test pour verifier que `docmachine build --help` expose bien `--cache` et `--no-cache`. `crystal spec --error-trace` OK (23 examples).