Refactor zainod CLI: add generate-config command and XDG config support by nachog00 · Pull Request #854 · zingolabs/zaino

nachog00 · 2026-02-18T22:15:07Z

This update refactors the zainod CLI to utilize explicit subcommands, introduces a generate-config utility, and adopts the XDG Base Directory specification for improved configuration management.

Breaking Changes

The CLI now requires a specific subcommand to operate.

Previous usage: zainod --config path.toml
New usage: zainod start or zainod start -c path.toml

Important

Running zainod without a subcommand will now print the help menu and exit. All automated integrations or scripts must be updated to include the start command.

Core Benefits

Effortless Setup: The generate-config command allows users to create a valid, up-to-date configuration file instantly.
Reduced Maintenance: Removed zindexer.toml. Configuration is now generated directly from the codebase, ensuring the "example" never drifts from actual default values.
Cleaner Filesystems: By following XDG standards, the daemon keeps user home directories organized and compliant with modern Linux standards.
Better Docs: Configuration options are now documented via doc comments on internal types, making them easily accessible through cargo docs.

Detailed Changes

CLI & Configuration

Subcommand Restructure: Migrated from flags to subcommands. The start command now explicitly represents the daemon's behavior.
XDG Compliance: Default config path is now $XDG_CONFIG_HOME/zaino/zainod.toml (falling back to ~/.config/zaino/zainod.toml).
New Utility: Added zainod generate-config, which writes the default setup to the XDG path or a custom location via the -o flag.

Technical Fixes

TOML Serialization: Resolved several serde issues:
DatabaseSize: Simplified to a newtype struct.
Network: Added a bidirectional serde helper.
ZainodConfig: Reordered fields to ensure values appear before tables, satisfying TOML requirements.

Documentation

Migrated all configuration descriptions from zindexer.toml into code-level doc comments.
Updated use_cases.md to reflect the new CLI syntax.

Testing

To ensure stability, the following tests were implemented:

test_generate_default_config_produces_valid_toml: Validates the output of the generation tool.
test_config_roundtrip_serialize_deserialize: Prevents regressions in field ordering and serialization logic.

- Extract CLI parsing to dedicated cli.rs module with Command enum - Move indexer loop and logging init from main.rs to lib.rs run() - main.rs now only parses CLI and dispatches to command handlers - Add generate-config subcommand for creating default config files - Require explicit subcommand: `zainod run` or `zainod generate-config`

- Add GENERATED_CONFIG_HEADER const to lib.rs - Move generate_default_config() function to lib.rs for testability - cli.rs now delegates to lib.rs for config generation logic - DEFAULT_CONFIG_PATH stays in cli.rs as it's a binary concern

- DatabaseSize: simplify from enum to newtype struct with #[serde(transparent)] - Network: add serde into/from for consistent string serialization - ZainodConfig: reorder fields (values before tables) per TOML spec Enables `zainod generate-config` to produce valid TOML output.

Ensures serialize → deserialize → serialize produces stable output. Catches regressions in field ordering and custom serde impls.

Relocates GENERATED_CONFIG_HEADER, generate_default_config(), and related tests from lib.rs to config.rs where they belong.

Default config location is now $XDG_CONFIG_HOME/zaino/zainod.toml, falling back to ~/.config/zaino/zainod.toml if XDG_CONFIG_HOME is unset.

- Renamed 'run' subcommand to 'start' (better conveys daemon behavior) - generate-config now writes to default XDG config path when -o is omitted - Creates parent directories automatically if needed

Reflects 'zainod start' subcommand and generate-config usage.

Moved useful documentation from zindexer.toml into doc comments on config structs (ValidatorConfig, BackendType, CacheConfig, ZainodConfig). Removed zindexer.toml - users should use 'zainod generate-config' instead. This avoids maintenance burden of keeping an example file in sync with code changes. Config documentation now lives in cargo docs.

Move error handling responsibility to the binary. The run() function now returns Result<(), IndexerError> instead of handling exits internally. This allows the binary to decide how to handle errors (exit code, logging). Addresses issue #807 point 1: config failures now exit gracefully with clear error messages instead of panicking.

Add centralized XDG path resolution policy in zaino-common/src/xdg.rs. This provides consistent default path handling across Zaino: - XdgDir enum with Config and Cache variants - resolve_path_with_xdg_{config,cache}_defaults() convenience functions - Fallback chain: $XDG_VAR -> $HOME/.{subdir} -> /tmp/zaino/.{subdir} Update zainod to use these utilities: - cli.rs: default_config_path() now uses XDG config defaults - config.rs: default_zaino_db_path() and default_zebra_db_path() use XDG cache defaults Fixes issue #807 point 2: zebra_db_path no longer panics on missing HOME. Instead of failing at config construction, invalid paths are detected at runtime when actually accessed, providing clearer error messages.

Update DatabaseConfig::default() in zaino-common to use resolve_path_with_xdg_cache_defaults("zaino") instead of the hardcoded relative path "./zaino_cache". This ensures consistent XDG-compliant paths across all storage defaults. Remove now-redundant default_zaino_db_path() from zainod config and simplify ZainodConfig::default() to use StorageConfig::default().

nachog00 · 2026-02-18T23:42:10Z

Additional work addressing #807:

The last three commits address issues 1 and 2 from #807:

8d1e0b4: run() now returns Result<(), IndexerError> instead of handling exits internally. The binary decides exit behavior, and config loading errors are reported gracefully rather than panicking.
01d363b: Introduces zaino-common::xdg module with centralized XDG Base Directory utilities. Path resolution follows the policy: $XDG_VAR -> $HOME/.{subdir} -> /tmp/zaino/.{subdir}. This eliminates panics when HOME is unset.
a37b96a: Updates DatabaseConfig::default() to use resolve_path_with_xdg_cache_defaults("zaino") instead of the hardcoded relative path ./zaino_cache.

Issue 3 from #807 (documentation referencing non-existent no_db option) requires further investigation and will be addressed in a separate issue.

nachog00 · 2026-02-19T18:02:39Z

>>> Running tests using:
>>> -- IMAGE             = zingodevops/zaino-ci
>>> -- TAG               = RUST_1.92-ZCASH_6.3.0-ZEBRA_3.1.0-DOCKER_9229da2adb2857

Summary [1557.166s] 330 tests run: 330 passed (54 slow), 32 skipped

fluidvanadium

Code-reviewed.

Command-tested.

str4d · 2026-02-23T21:00:42Z

zaino-common/src/xdg.rs

+    // /// `XDG_DATA_HOME` - User data files.
+    // ///
+    // /// Default: `$HOME/.local/share`
+    // Data,
+
+    // /// `XDG_STATE_HOME` - Persistent state (logs, history).
+    // ///
+    // /// Default: `$HOME/.local/state`
+    // State,


Be very careful about using these: https://bsky.app/profile/str4d.xyz/post/3lsjbnpsbh22i

I don't have an account on that platform. Could you elaborate on your concerns? I understand they revolve around the XDG_DATA_HOME specifically.

nachog00 added 9 commits February 18, 2026 17:30

test(zainod): add config roundtrip test

7645da5

Ensures serialize → deserialize → serialize produces stable output. Catches regressions in field ordering and custom serde impls.

refactor(zainod): move config generation to config module

e5206f6

Relocates GENERATED_CONFIG_HEADER, generate_default_config(), and related tests from lib.rs to config.rs where they belong.

feat(cli): use XDG Base Directory for default config path

5e42330

Default config location is now $XDG_CONFIG_HOME/zaino/zainod.toml, falling back to ~/.config/zaino/zainod.toml if XDG_CONFIG_HOME is unset.

feat(cli): rename 'run' to 'start', generate-config writes to XDG path

01c7a34

- Renamed 'run' subcommand to 'start' (better conveys daemon behavior) - generate-config now writes to default XDG config path when -o is omitted - Creates parent directories automatically if needed

docs: update use_cases.md for new CLI commands

1865b6f

Reflects 'zainod start' subcommand and generate-config usage.

nachog00 requested a review from fluidvanadium February 18, 2026 22:15

nachog00 added documentation Improvements or additions to documentation Configs Related to overall configuration of zaino zainod problems that concern zainod (binary) labels Feb 18, 2026

This was linked to issues Feb 18, 2026

generate-config command #741

Closed

zainod config example is outdated #742

Closed

nachog00 added 3 commits February 18, 2026 19:40

This was referenced Feb 18, 2026

Config improvements: error handling and documentation updates #807

Closed

Documentation mentions no_db option that doesn't exist #855

Open

nachog00 linked an issue Feb 18, 2026 that may be closed by this pull request

Config improvements: error handling and documentation updates #807

Closed

fluidvanadium self-assigned this Feb 19, 2026

nachog00 mentioned this pull request Feb 20, 2026

improve example config #822

Closed

fluidvanadium approved these changes Feb 20, 2026

View reviewed changes

fluidvanadium merged commit 039ca21 into dev Feb 20, 2026
5 of 10 checks passed

str4d reviewed Feb 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Refactor zainod CLI: add generate-config command and XDG config support#854

Refactor zainod CLI: add generate-config command and XDG config support#854
fluidvanadium merged 12 commits intodevfrom
refactor/minimal-main

nachog00 commented Feb 18, 2026 •

edited

Loading

Uh oh!

nachog00 commented Feb 18, 2026

Uh oh!

nachog00 commented Feb 19, 2026 •

edited

Loading

Uh oh!

fluidvanadium left a comment

Uh oh!

Uh oh!

str4d Feb 23, 2026

Uh oh!

nachog00 Feb 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

nachog00 commented Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking Changes

Core Benefits

Detailed Changes

CLI & Configuration

Technical Fixes

Documentation

Testing

Uh oh!

nachog00 commented Feb 18, 2026

Uh oh!

nachog00 commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fluidvanadium left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

str4d Feb 23, 2026

Choose a reason for hiding this comment

Uh oh!

nachog00 Feb 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nachog00 commented Feb 18, 2026 •

edited

Loading

nachog00 commented Feb 19, 2026 •

edited

Loading