/**
 * @file metadata.hpp
 * @brief Module records: what libdpm-core.so knows without loading a module
 *
 * @copyright Copyright (c) 2026 SILO GROUP LLC
 * @author Chris Punches <chris.punches@silogroup.org>
 *
 * Part of the Dark Horse Linux Package Manager (DPM)
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
#pragma once

#include <map>
#include <string>

struct dpm_ctx;

/**
 * @brief The records one module's .meta file carries
 *
 * Written when a module is installed, from what the module itself
 * reported at that moment. A listing reports these values, so a listing
 * needs to open no module.
 */
struct dpm_module_meta_records {
    /** Basename of the module file these records describe. */
    std::string module_file;

    /** Version the module reported when it was installed. */
    std::string version;

    /** Description the module reported when it was installed. */
    std::string description;
};

namespace dpm_core {
    /**
     * @brief Reads a flat key/value file from the metadata directory
     *
     * The format every file in that directory uses: one `key = value`
     * per line, '#' and ';' opening a comment, and every key and value
     * trimmed. A line carrying no '=' is skipped, so a malformed line
     * costs that line and no more.
     *
     * @param path The file to read
     * @param out Receives the pairs the file carried
     * @return true when the file was opened; false when it was not
     */
    bool md_read_key_value_file(const std::string& path,
                                std::map<std::string, std::string>& out);

    /**
     * @brief Writes a flat key/value file into the metadata directory
     *
     * Creates the directory when it is absent, and replaces the file's
     * whole contents.
     *
     * @param path The file to write
     * @param values The pairs to write, one per line
     * @param reason Receives the failure reason when the write fails
     * @return true on success
     */
    bool md_write_key_value_file(
        const std::string& path,
        const std::map<std::string, std::string>& values,
        std::string& reason);

    /**
     * @brief Reads every module record in a context's metadata directory
     *
     * Each .meta file becomes one set of records named after the file
     * without its extension. A missing or unreadable directory leaves
     * the context holding no records, which costs a listing its detail
     * and costs nothing else.
     *
     * @param ctx The libdpm-core.so context
     */
    void md_load_records_dir(dpm_ctx* ctx);

    /**
     * @brief Finds the records for a module name
     *
     * @param ctx The libdpm-core.so context
     * @param module_name The module name to look up
     * @return The records, or nullptr when no module of that name is recorded
     */
    const dpm_module_meta_records* md_find_module_record(
        dpm_ctx* ctx, const std::string& module_name);

    /**
     * @brief Writes one module's records into the metadata directory
     *
     * Replaces the records of the same module name, and updates the
     * context's own copy so the change is visible without reopening.
     *
     * @param ctx The libdpm-core.so context
     * @param module_name The module name the records belong to
     * @param records The records to write
     * @param reason Receives the failure reason when the write fails
     * @return true on success
     */
    bool md_write_module_record(dpm_ctx* ctx, const std::string& module_name,
                                const dpm_module_meta_records& records,
                                std::string& reason);

    /**
     * @brief Removes one module's records from the metadata directory
     *
     * @param ctx The libdpm-core.so context
     * @param module_name The module name whose records are removed
     * @param reason Receives the failure reason when the removal fails
     * @return true on success
     */
    bool md_remove_module_record(dpm_ctx* ctx, const std::string& module_name,
                                 std::string& reason);
} // namespace dpm_core