mdl – host CLI for the e-reader media downloader. More...

#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <signal.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <unistd.h>
#include "fw_if_fs_posix.h"
#include "mdl_app.h"
#include "mdl_cli_internal.h"
#include "mdl_compose_internal.h"
#include "mdl_host_credentials_internal.h"
#include "mdl_sanitize.h"
#include "mdl_stream_internal.h"
#include "ra8_attributes.h"
#include "ra8_io_stream_posix.h"

Include dependency graph for main.c:

Data Structures
struct	export_arena_storage_t
	Naturally aligned, caller-owned exporter workspace storage. More...
struct	storage_workspace_t
	Maximally aligned storage for one filesystem backend handle. More...
struct	directory_workspace_t
	Maximally aligned storage for one filesystem directory cursor. More...

Enumerations
enum	credential_input_capacity_t : size_t { k_cookie_input_capacity = 64U * 1024U , k_ca_pem_input_capacity = 512U * 1024U }
	Explicit host credential input capacities. More...

Functions
static ra8_err_t	internal_output_init (void)
	Bind process output descriptors and surface broken pipes as errors.
static ra8_err_t	internal_diagnostic (const char *message)
	Write one fixed process diagnostic through the injected sink.
static ra8_err_t	internal_read_credential (int fd, const struct stat before, uint8_t destination, size_t length)
	Read one already-open credential file and reject concurrent mutation.
static ra8_err_t	internal_load_credential (const char path, uint8_t destination, size_t supplied, size_t required, size_t used)
	Load one path argument into exact caller-supplied credential storage.
static ra8_err_t	internal_credential_capacity_error (ra8_io_stream_t diagnostic, const char option, size_t required, size_t supplied)
	Emit an exact required-versus-supplied credential capacity error.
static ra8_err_t	internal_prepare_credentials (const mdl_args_t args, mdl_net_policy_t policy, ra8_io_stream_t *diagnostic)
	Snapshot optional host credential paths into portable byte policy.
static int	internal_exit_from_error (ra8_err_t err, bool usage_error)
	Convert one CLI or output status to the process exit convention.
static ra8_err_t	internal_storage_init (void)
	Bind the host root through the POSIX composition adapter.
static ra8_err_t	internal_resolve_config_path (mdl_args_t *args)
	Resolve an optional host config argument into the root-bound namespace.
static ra8_err_t	internal_resolve_one_leaf (const char input, char destination, size_t capacity)
	Resolve a library root, including one absent final directory.
static ra8_err_t	internal_resolve_output_path (mdl_args_t *args)
	Canonicalize the command output root with one absent leaf allowed.
static ra8_err_t	internal_resolve_cache_path (mdl_args_t *args)
	Resolve or derive the persistent per-host cache root.
static bool	internal_uses_output_path (mdl_cli_mode_t mode)
	True when a validated mode consumes the canonical output root.
static bool	internal_uses_cache_path (mdl_cli_mode_t mode)
	Classify modes that perform persistent document caching.
static ra8_err_t	internal_resolve_pack_path (mdl_args_t *args)
	Canonicalize the existing pack input directory.
static ra8_err_t	internal_resolve_verify_path (mdl_args_t *args)
	Canonicalize a verify target while preserving absent-leaf diagnostics.
static ra8_err_t	internal_resolve_descriptor_path (mdl_args_t *args)
	Select the canonical init-site descriptor directory.
static int	internal_prepare_args (mdl_args_t args, mdl_cli_mode_t mode, ra8_io_stream_t diagnostic)
	Apply host defaults and canonicalize paths for the selected mode.
static int	internal_prepare_run_policy (const mdl_args_t args, mdl_run_opts_t opts, mdl_format_t *format)
	Validate output format and attach bounded credential byte views.
static int	internal_main_init (int argc, char *argv, mdl_args_t a)
	Bootstrap process I/O and workspace state, then parse arguments.
static int	internal_main_run (const mdl_args_t a, mdl_cli_mode_t mode, mdl_format_t format, const mdl_run_opts_t opts, const mdl_nums_t *nums)
	Build the series-run plan, then dispatch and shut down cleanly.
int	main (int argc, char **argv)
	Program entry point: parse the command line and select a run mode.

Variables
static export_arena_storage_t	s_export_arena
	Process-lifetime exporter workspace storage (zero heap).
static fw_fs_t	s_fs
	Host-selected filesystem facade and adapter state.
static fw_fs_posix_state_t	s_fs_posix = {.root_fd = -1}
static storage_workspace_t	s_fs_file_work
	One file and one transaction workspace for single-threaded storage.
static storage_workspace_t	s_fs_transaction_work
static directory_workspace_t	s_fs_directory_work
	One bounded host directory-cursor workspace.
static uint8_t	s_fs_io_buffer [k_mdl_storage_io_bytes]
	Caller-owned streaming buffer shared by serial storage operations.
static char	s_config_path [PATH_MAX]
	Canonical host config path retained through one command run.
static char	s_library_path [PATH_MAX]
	Canonical host library root retained through one command run.
static char	s_cache_path [PATH_MAX]
	Canonical host cache root retained through one command run.
static char	s_mode_path [PATH_MAX]
	Canonical verify, pack, or descriptor path retained for one run.
static uint8_t	s_cookie_input [k_cookie_input_capacity]
	Process-lifetime, caller-owned cookie input bytes.
static uint8_t	s_ca_pem_input [k_ca_pem_input_capacity]
	Process-lifetime, caller-owned custom CA PEM bytes.
static mdl_app_context_t	s_app
	Process-lifetime bounded application state.
static ra8_io_stream_t	s_output
	Process stdout and stderr exposed through the portable byte-stream facade.
static ra8_io_stream_t	s_diagnostic
static ra8_io_stream_posix_state_t	s_output_posix
	Borrowed raw-descriptor backend state for process output streams.
static ra8_io_stream_posix_state_t	s_diagnostic_posix

Detailed Description

mdl – host CLI for the e-reader media downloader.

Native host binary that links the firmware error contract (ra8_err_t) and drives the downloader logic that will later run on the RA8 (only the injected libcurl backend is host-specific). Modes:

series (--config S.conf --series URL): read a site descriptor, list a series' chapters, and download them into a reader-openable file. Selection is by chapter identity, not list position: --from CHAP starts at the chapter NUMBERED CHAP, and --update fetches only chapters not already recorded complete in the per-series library state. Downloads resume after interruption and never re-fetch a page whose bytes are already held.
library (over --out): --list shows tracked series with coverage and gaps, --update-all incrementally updates every tracked series, --remove drops one series.
pack (--pack DIR --format FMT): package an existing image folder with no network.
page (bare URL): fetch one page and download its <img> URLs.

The tool identifies itself honestly, honours robots.txt by default, and sanitises every untrusted name before it reaches the filesystem.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file main.c.

Enumeration Type Documentation

◆ credential_input_capacity_t

enum credential_input_capacity_t : size_t

Explicit host credential input capacities.

Enumerator
k_cookie_input_capacity	Maximum cookie-file bytes.
k_ca_pem_input_capacity	Maximum custom CA bytes.

Definition at line 64 of file main.c.

Function Documentation

◆ internal_credential_capacity_error()

ra8_err_t internal_credential_capacity_error	(	ra8_io_stream_t *	diagnostic,
		const char *	option,
		size_t	required,
		size_t	supplied )

static

Emit an exact required-versus-supplied credential capacity error.

Parameters

[in,out]	diagnostic	Bound diagnostic byte stream.
[in]	option	NUL-terminated CLI option name.
[in]	required	Exact observed input bytes.
[in]	supplied	Exact caller-owned capacity bytes.

Returns: First stream error, or k_ra8_ok.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition: Every required pointer is non-null and remains valid for the call.; Lengths and capacities describe complete referenced objects without overflow.

Postcondition: Documented outputs and the return value describe the same outcome.; A rejected or failed operation is never reported as successful.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 277 of file main.c.

References k_ra8_ok, priv_mdl_stream_text(), priv_mdl_stream_u64(), and RA8_INTERNAL.

Referenced by internal_prepare_credentials().

◆ internal_diagnostic()

ra8_err_t internal_diagnostic ( const char * message )

static

Write one fixed process diagnostic through the injected sink.

Parameters

[in] message NUL-terminated diagnostic including its newline.

Returns: Canonical stream status.

Precondition: message is non-NULL and NUL-terminated.; internal_output_init completed successfully.

Postcondition: Success writes the complete diagnostic without C-runtime buffering.; Failure is returned without retrying at another destination.

Note: Not thread-safe with concurrent writes to s_diagnostic.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Definition at line 150 of file main.c.

References RA8_INTERNAL, ra8_io_stream_puts(), and s_diagnostic.

Referenced by internal_main_run().

◆ internal_exit_from_error()

int internal_exit_from_error	(	ra8_err_t	err,
		bool	usage_error )

static

Convert one CLI or output status to the process exit convention.

Parameters

[in]	err	Canonical operation status.
[in]	usage_error	Whether invalid argument maps to usage exit 2.

Returns: Process exit status.

Return values

0	`err` is k_ra8_ok.
2	`usage_error` is true and `err` is invalid-argument.
1	Every output or operational failure.

Precondition: err is a canonical ra8_err_t value.; The caller has already emitted any applicable diagnostic.

Postcondition: No stream or process state is modified.

Note: Thread-safe: pure value mapping.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Postcondition: Documented outputs and the return value describe the same outcome.

Definition at line 379 of file main.c.

References k_ra8_err_invalid_arg, k_ra8_ok, and RA8_INTERNAL.

Referenced by internal_prepare_run_policy(), and main().

◆ internal_load_credential()

ra8_err_t internal_load_credential	(	const char *	path,
		uint8_t *	destination,
		size_t	supplied,
		size_t *	required,
		size_t *	used )

static

Load one path argument into exact caller-supplied credential storage.

Parameters

[in]	path	Host path accepted only at this composition boundary.
[out]	destination	Caller-owned credential byte storage.
[in]	supplied	Exact destination capacity in bytes.
[out]	required	Source size required for a complete snapshot.
[out]	used	Complete stable byte count on success.

Returns: Canonical path, type, capacity, read, or mutation status.

Return values

k_ra8_ok	A stable regular-file snapshot was retained.
k_ra8_err_invalid_arg	The source is not a regular file.
k_ra8_err_invalid_size	The source exceeds `supplied`.
k_ra8_err_access_denied	Open, stat, read, mutation, or close failed.

Precondition: All pointer arguments are non-NULL and path is NUL-terminated.

Postcondition: required reports the observed source size when representable.; Success sets used to required; failure leaves used zero.

Note: O_NOFOLLOW rejects a symlink at the final component.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Precondition: Every required pointer is non-null and remains valid for the call.

Definition at line 223 of file main.c.

References internal_read_credential(), k_ra8_err_access_denied, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, O_CLOEXEC, O_NOFOLLOW, and RA8_INTERNAL.

Referenced by internal_prepare_credentials().

◆ internal_main_init()

int internal_main_init	(	int	argc,
		char **	argv,
		mdl_args_t *	a )

static

Bootstrap process I/O and workspace state, then parse arguments.

Initializes the output stream and composition-root context, binds the fixed export arena, and parses argv into a.

Parameters

[in]	argc	Argument count.
[in]	argv	Argument vector.
[out]	a	Receives the parsed (not yet validated) command arguments.

Returns: Process-style bootstrap status.

Return values

0	Output, context, and argument parsing are ready.
1	Output stream initialization failed.

Precondition: argv is non-NULL and holds argc entries.; a addresses writable storage for one complete mdl_args_t.

Postcondition: On success a holds the raw parsed arguments.; A failed output-stream init binds no context and no export arena.

Note: Not thread-safe; initializes process-lifetime shared state.

Since: 0.1.0

Definition at line 829 of file main.c.

References internal_output_init(), k_ra8_ok, mdl_app_bind(), mdl_cli_parse(), mdl_export_workspace_init(), RA8_INTERNAL, s_app, s_diagnostic, s_export_arena, and s_output.

Referenced by main().

◆ internal_main_run()

int internal_main_run	(	const mdl_args_t *	a,
		mdl_cli_mode_t	mode,
		mdl_format_t	format,
		const mdl_run_opts_t *	opts,
		const mdl_nums_t *	nums )

static

Build the series-run plan, then dispatch and shut down cleanly.

Binds the portable filesystem, dispatches to the selected mode handler, and always attempts filesystem shutdown before returning.

Parameters

[in]	a	Validated parsed command arguments.
[in]	mode	Selected run mode.
[in]	format	Validated output format.
[in]	opts	Prepared run policy.
[in]	nums	Parsed numeric options.

Returns: Process-style run status.

Return values

0	The dispatched mode completed successfully.
1	Filesystem binding or shutdown failed.
other	The dispatched mode's own failure status.

Precondition: All pointers are non-NULL.; opts already carries the credential views the run policy prepared.

Postcondition: Filesystem shutdown is attempted exactly once regardless of outcome.; No mode handler runs when the portable filesystem binding fails.

Note: Not thread-safe; binds and releases process-lifetime storage.

Since: 0.1.0

Definition at line 863 of file main.c.

References fw_fs_posix_deinit(), internal_diagnostic(), internal_storage_init(), k_ra8_ok, priv_mdl_compose_build_run(), priv_mdl_compose_dispatch(), RA8_INTERNAL, and s_fs_posix.

Referenced by main().

◆ internal_output_init()

ra8_err_t internal_output_init ( void )

static

Bind process output descriptors and surface broken pipes as errors.

Returns: Canonical composition status.

Return values

k_ra8_ok	Both output streams are ready.
k_ra8_err_comm_error	The process signal disposition could not be installed.
other	A raw-descriptor stream binding failed.

Precondition: Standard output and standard error descriptors are process-owned.; No output operation has started.

Postcondition: Success binds borrowed descriptors for the process lifetime.; SIGPIPE is ignored so descriptor writes return EPIPE to the adapter.

Note: Host composition only; no descriptor ownership is transferred.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Definition at line 121 of file main.c.

References k_ra8_err_comm_error, k_ra8_ok, RA8_INTERNAL, ra8_io_stream_posix_init(), s_diagnostic, s_diagnostic_posix, s_output, and s_output_posix.

Referenced by internal_main_init().

◆ internal_prepare_args()

int internal_prepare_args	(	mdl_args_t *	args,
		mdl_cli_mode_t	mode,
		ra8_io_stream_t *	diagnostic )

static

Apply host defaults and canonicalize paths for the selected mode.

Parameters

[in,out]	args	Validated parsed arguments.
[in]	mode	Validated CLI mode.
[in,out]	diagnostic	Bound stream receiving preparation diagnostics.

Returns: Process-style preparation status.

Return values

0	Defaults and required host paths are ready.
1	A required config or library path could not be resolved.

Precondition: args and diagnostic are non-NULL and mode came from mdl_cli_validate.; Optional argument strings remain NUL-terminated.

Postcondition: Success supplies default output/image-attribute strings when absent.; Every domain-facing filesystem path is canonical and portable-sized.

Note: The ignore-robots warning is emitted exactly once here.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Definition at line 740 of file main.c.

References mdl_args_t::attr, mdl_args_t::ignore_robots, internal_resolve_cache_path(), internal_resolve_config_path(), internal_resolve_descriptor_path(), internal_resolve_output_path(), internal_resolve_pack_path(), internal_resolve_verify_path(), internal_uses_cache_path(), internal_uses_output_path(), k_mdl_cli_mode_init_site, k_mdl_cli_mode_pack, k_mdl_cli_mode_verify, k_ra8_ok, mdl_args_t::out, and ra8_io_stream_puts().

Referenced by main().

◆ internal_prepare_credentials()

ra8_err_t internal_prepare_credentials	(	const mdl_args_t *	args,
		mdl_net_policy_t *	policy,
		ra8_io_stream_t *	diagnostic )

static

Snapshot optional host credential paths into portable byte policy.

Parameters

[in]	args	Validated CLI arguments retaining host-only paths.
[in,out]	policy	Network policy receiving read-only byte views.
[in,out]	diagnostic	Bound diagnostic stream.

Returns: Canonical credential preparation status.

Precondition: All arguments are non-NULL and credential paths are NUL-terminated.

Postcondition: Success exposes no credential path beyond this composition function.; Failure leaves both policy byte views empty.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Return values

k_ra8_ok	The operation completed successfully.
other	The originating validation, storage, stream, or network error.

Precondition: Every required pointer is non-null and remains valid for the call.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 309 of file main.c.

References mdl_args_t::ca_file, mdl_net_policy_t::ca_pem, mdl_args_t::cookie_file, mdl_net_policy_t::cookies, internal_credential_capacity_error(), internal_load_credential(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_ok, RA8_INTERNAL, ra8_io_stream_puts(), s_ca_pem_input, and s_cookie_input.

Referenced by internal_prepare_run_policy().

◆ internal_prepare_run_policy()

int internal_prepare_run_policy	(	const mdl_args_t *	args,
		mdl_run_opts_t *	opts,
		mdl_format_t *	format )

static

Validate output format and attach bounded credential byte views.

Parameters

[in]	args	Validated parsed command arguments.
[in,out]	opts	Mutable run policy receiving credential views.
[out]	format	Validated output format.

Returns: Process-style preparation status.

Return values

0	Format and credential policy are ready.
1	Credential preparation failed.
2	The requested format is invalid.

Precondition: All arguments are non-NULL and process diagnostics are bound.

Postcondition: Success leaves opts and format ready for the complete run.; Failure performs no network or portable storage operation.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Precondition: Every required pointer is non-null and remains valid for the call.

Note: Thread safety follows ownership of the supplied context; no synchronization is added.

Definition at line 798 of file main.c.

References mdl_args_t::format, internal_exit_from_error(), internal_prepare_credentials(), k_mdl_format_invalid, k_ra8_ok, mdl_format_from_str(), mdl_run_opts_t::policy, priv_mdl_cli_reject_parts(), and s_diagnostic.

Referenced by main().

◆ internal_read_credential()

ra8_err_t internal_read_credential	(	int	fd,
		const struct stat *	before,
		uint8_t *	destination,
		size_t	length )

static

Read one already-open credential file and reject concurrent mutation.

Parameters

[in]	fd	Raw descriptor pinned to the selected regular file.
[in]	before	Metadata captured immediately after open.
[out]	destination	Caller-owned credential storage.
[in]	length	Exact expected file length.

Returns: Canonical read or mutation status.

Return values

k_ra8_ok	Exactly `length` stable bytes were read.
k_ra8_err_access_denied	A read/stat failed or the source mutated.

Precondition: fd is readable and destination has at least length bytes.

Postcondition: Success fills exactly length bytes and observes EOF at that extent.; Failure publishes no byte-view length to portable policy.

Note: Host composition only; reads are positioned and bounded.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Precondition: Every required pointer is non-null and remains valid for the call.

Definition at line 175 of file main.c.

References k_ra8_err_access_denied, k_ra8_ok, and priv_mdl_host_credential_stat_unchanged().

Referenced by internal_load_credential().

◆ internal_resolve_cache_path()

ra8_err_t internal_resolve_cache_path ( mdl_args_t * args )

static

Resolve or derive the persistent per-host cache root.

Uses the explicit cache path when supplied; otherwise joins the fixed .mdl_cache leaf beneath the canonical output root.

Parameters

[in,out] args Parsed arguments receiving the canonical cache path.

Returns: Canonical host-path status.

Return values

k_ra8_ok	The cache root is canonical and portable-sized.
other	The supplied or derived path is unsafe or too large.

Precondition: args is non-NULL and its output root is canonical.; A supplied cache path has at most one absent final component.

Postcondition: Success points cache_dir at process-lifetime storage.; The default is exactly OUT/.mdl_cache.

Note: Directory creation occurs later through the portable storage facade.

Since: 0.1.0

Definition at line 555 of file main.c.

References mdl_args_t::cache_dir, internal_resolve_one_leaf(), k_ra8_err_invalid_size, k_ra8_ok, mdl_path_join(), mdl_args_t::out, RA8_INTERNAL, and s_cache_path.

Referenced by internal_prepare_args().

◆ internal_resolve_config_path()

ra8_err_t internal_resolve_config_path ( mdl_args_t * args )

static

Resolve an optional host config argument into the root-bound namespace.

Parameters

[in,out] args Parsed command arguments whose config pointer may change.

Returns: Canonicalization status.

Return values

k_ra8_ok	No config was supplied or its canonical path was retained.
k_ra8_err_not_found	The host could not resolve the supplied path.

Precondition: args is non-NULL and its optional config string is NUL-terminated.; The host composition binds portable storage at /.

Postcondition: Success with a config points args->cfg at process-lifetime storage.; No portable/domain reader observes a relative or symlinked host path.

Note: Host composition only; device composition supplies canonical VFS paths.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Definition at line 444 of file main.c.

References mdl_args_t::cfg, k_fw_fs_path_cap, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_ok, RA8_INTERNAL, s_config_path, and strlen().

Referenced by internal_prepare_args().

◆ internal_resolve_descriptor_path()

ra8_err_t internal_resolve_descriptor_path ( mdl_args_t * args )

static

Select the canonical init-site descriptor directory.

Uses a real sites child only when lstat proves the child is a directory rather than a symlink; otherwise it selects the current canonical directory. Unexpected inspection failures stop the run.

Parameters

[in,out] args Parsed arguments whose output field receives the directory.

Returns: Canonical host-composition status.

Return values

k_ra8_ok	A safe portable-sized descriptor directory was selected.
k_ra8_err_not_found	The current directory could not be resolved.
k_ra8_err_access_denied	The candidate child could not be inspected.
k_ra8_err_invalid_size	The selected namespace exceeds the path cap.

Precondition: args is non-null and init-site mode was validated.; The process current directory remains stable during preparation.

Postcondition: Success points args->out at process-lifetime canonical storage.; Failure publishes no descriptor path to application code.

Note: Host composition only; the app itself has no current-directory policy.

Since: 0.1.0

Definition at line 696 of file main.c.

References k_fw_fs_path_cap, k_ra8_err_access_denied, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_ok, mdl_path_join(), memcpy(), mdl_args_t::out, RA8_INTERNAL, s_mode_path, and strlen().

Referenced by internal_prepare_args().

◆ internal_resolve_one_leaf()

ra8_err_t internal_resolve_one_leaf	(	const char *	input,
		char *	destination,
		size_t	capacity )

static

Resolve a library root, including one absent final directory.

Existing roots pass through realpath; for an absent root only its existing canonical parent is resolved and one safe leaf is joined.

Parameters

[in]	input	Existing canonical path or path with one absent final leaf.
[out]	destination	Receives the canonical absolute path.
[in]	capacity	Writable bytes at `destination`.

Returns: Canonical host-composition status.

Return values

k_ra8_ok	The root is canonical and retained for the command lifetime.
k_ra8_err_not_found	The path or its immediate parent cannot resolve.
k_ra8_err_invalid_arg	The absent final component is unsafe.

Precondition: input and destination are non-NULL and input is NUL-terminated.; The host storage composition is bound to /.

Postcondition: Success NUL-terminates destination within capacity.; Domain library code never receives a relative or unresolved host path.

Note: Host composition only; firmware supplies canonical VFS paths directly.

Since: 0.1.0

Definition at line 478 of file main.c.

References k_fw_fs_path_cap, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_ok, mdl_path_join(), memcpy(), strcmp(), strlen(), and strrchr().

Referenced by internal_resolve_cache_path(), and internal_resolve_output_path().

◆ internal_resolve_output_path()

ra8_err_t internal_resolve_output_path ( mdl_args_t * args )

static

Canonicalize the command output root with one absent leaf allowed.

Resolves the existing directory or its canonical parent, then redirects the parsed output view to process-lifetime storage.

Parameters

[in,out] args Parsed arguments whose output pointer is replaced.

Returns: Canonical host-composition status.

Return values

k_ra8_ok	The output root is canonical and portable-sized.
other	The path is missing, unsafe, or too large.

Precondition: args and args->out are non-NULL and NUL-terminated.; Host path composition is bound for the command lifetime.

Postcondition: Success points args->out at process-lifetime storage.; Failure leaves args->out unchanged.

Note: Host composition only; portable runners receive canonical paths.

Since: 0.1.0

Definition at line 529 of file main.c.

References internal_resolve_one_leaf(), k_ra8_ok, mdl_args_t::out, RA8_INTERNAL, and s_library_path.

Referenced by internal_prepare_args(), and internal_resolve_verify_path().

◆ internal_resolve_pack_path()

ra8_err_t internal_resolve_pack_path ( mdl_args_t * args )

static

Canonicalize the existing pack input directory.

Parameters

[in,out] args Parsed arguments whose pack pointer is replaced.

Returns: Canonical host-composition status.

Return values

k_ra8_ok	The selected input is canonical and portable-sized.
k_ra8_err_not_found	The selected directory cannot be resolved.
k_ra8_err_invalid_size	The canonical path exceeds the facade cap.

Precondition: args is non-null and args->pack is NUL-terminated.; Pack mode was selected by mdl_cli_validate.

Postcondition: Success points args->pack at process-lifetime storage.; Failure leaves the parsed pointer unchanged.

Note: Host composition only; portable runners receive canonical paths.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Definition at line 633 of file main.c.

References k_fw_fs_path_cap, k_ra8_err_invalid_size, k_ra8_err_not_found, k_ra8_ok, mdl_args_t::pack, RA8_INTERNAL, s_mode_path, and strlen().

Referenced by internal_prepare_args().

◆ internal_resolve_verify_path()

ra8_err_t internal_resolve_verify_path ( mdl_args_t * args )

static

Canonicalize a verify target while preserving absent-leaf diagnostics.

Reuses output-root resolution so one missing final component becomes a canonical portable path; the verifier then reports the specific unreadable-directory failure instead of preparation masking it.

Parameters

[in,out] args Parsed arguments whose selected verify path is replaced.

Returns: Canonical host-composition status.

Return values

k_ra8_ok	The verify target is canonical and portable-sized.
other	The target or its immediate parent cannot be resolved safely.

Precondition: args is non-null and its selected verify path is NUL-terminated.; Verify mode was selected by mdl_cli_validate.

Postcondition: Success updates verify_dir when explicit, otherwise out.; Failure restores the original out pointer.

Note: Host composition only; no filesystem mutation occurs.

Since: 0.1.0

Definition at line 661 of file main.c.

References internal_resolve_output_path(), k_ra8_ok, mdl_args_t::out, RA8_INTERNAL, and mdl_args_t::verify_dir.

Referenced by internal_prepare_args().

◆ internal_storage_init()

ra8_err_t internal_storage_init ( void )

static

Bind the host root through the POSIX composition adapter.

Performs storage init through the injected filesystem facade and keeps source and transaction handles caller-owned on every return path.

Returns: Canonical storage-composition status.

Return values

k_ra8_ok	The POSIX facade and downloader binding are ready.
other	POSIX adapter or workspace binding initialization failed.

Precondition: Process-lifetime storage objects are not currently initialized.; Static workspaces remain exclusively owned by the CLI thread.

Postcondition: Success leaves the shared storage binding ready until deinitialization.; Failure leaves no initialized POSIX adapter resource.

Note: Host composition only; firmware supplies a VFS facade instead.

Since: 0.1.0

Definition at line 401 of file main.c.

References fw_fs_posix_deinit(), fw_fs_posix_init(), k_ra8_ok, mdl_library_workspace_init(), mdl_storage_init(), RA8_INTERNAL, s_app, s_fs, s_fs_directory_work, s_fs_file_work, s_fs_io_buffer, s_fs_posix, and s_fs_transaction_work.

Referenced by internal_main_run().

◆ internal_uses_cache_path()

bool internal_uses_cache_path ( mdl_cli_mode_t mode )

static

Classify modes that perform persistent document caching.

Restricts cache-path setup to modes that may retrieve series, chapter, or cover documents through the cache coordinator.

Parameters

[in] mode Validated CLI mode.

Returns: Whether the mode may fetch a series or chapter index.

Return values

true	The selected mode may read or publish cache state.
false	The selected mode does not consume a cache path.

Precondition: mode is a valid enum value.; CLI mode selection has completed.

Postcondition: No process or argument state is modified.; True is limited to series/discovery/update modes.

Note: List/remove operations do not need the cache path.

Since: 0.1.0

Definition at line 610 of file main.c.

References k_mdl_cli_mode_browse, k_mdl_cli_mode_search, k_mdl_cli_mode_series, k_mdl_cli_mode_update_all, and RA8_INTERNAL.

Referenced by internal_prepare_args().

◆ internal_uses_output_path()

bool internal_uses_output_path ( mdl_cli_mode_t mode )

static

True when a validated mode consumes the canonical output root.

Parameters

[in] mode Validated command mode.

Returns: Whether args->out crosses into portable application code.

Return values

true	The mode consumes the output root.
false	The mode has no output-root dependency.

Precondition: mode was produced by mdl_cli_validate.; The caller has applied the default output string.

Postcondition: No argument or process state is modified.

Note: Thread-safe: pure value classification.

Since: 0.1.0

Uses process-lifetime caller-owned storage and injected I/O. Publishes no partial path or credential view after a failed validation.

Postcondition: Documented outputs and the return value describe the same outcome.

Definition at line 587 of file main.c.

References k_mdl_cli_mode_artifact, k_mdl_cli_mode_browse, k_mdl_cli_mode_list, k_mdl_cli_mode_page, k_mdl_cli_mode_remove, k_mdl_cli_mode_search, k_mdl_cli_mode_series, k_mdl_cli_mode_update_all, and RA8_INTERNAL.

Referenced by internal_prepare_args().

◆ main()

int main	(	int	argc,
		char **	argv )

Program entry point: parse the command line and select a run mode.

Parses and validates the arguments, then hands off to priv_mdl_compose_dispatch, which selects a library command (--list/--remove/--update-all), search/browse discovery (--search/--browse), pack mode (--pack), series mode (--config + --series), or single-page mode (a bare URL), in that precedence.

Parameters