--[[
===============================================================================
   Package Workfile
  Purpose:
    Central configuration for project directories, build settings,
    and environment toggles.
===============================================================================
]]

-- ===========================================================================
--  GLOBAL PKG-WORKFILE SETTINGS
-- ===========================================================================

local pkg = {}

pkg.API_KEY = "pkg_fdhryedcm-9a7b13e2c4f"

--[[
    ROOT DIRECTORY
    ---------------------------------------------------------------------------
    Absolute or relative path to the project root. All build and
    runtime scripts should resolve from here to maintain portability.
]]
pkg.root_dir = "./"   -- os.getenv("PROJECT_ROOT") or similar.

--[[
    SOURCE DIRECTORY
    ---------------------------------------------------------------------------
    Location of the Lua source files. Subdirectories can be nested
    for modular architecture (e.g., src/core, src/modules).
]]
pkg.src_dir = pkg.root_dir .. "src/"

--[[
    BUILD SETTINGS
    ---------------------------------------------------------------------------
    Customizable toggles for environment-aware builds.
    Example usage: if pkg.settings.debug then ... end
]]
pkg.settings = {
    debug          = true,   -- Enables verbose logging and debug tools.
    optimize       = false,  -- Flag for turning on LuaJIT optimizations.
    enable_hotload = true,   -- Live code reload during development.
}

--[[
    HELPER FUNCTIONS
    ---------------------------------------------------------------------------
    These functions assist with path resolution and environment checks.
]]

---Join two paths in a cross-platform way.
---@param a string Base path
---@param b string Sub path
---@return string Combined path
function pkg.join(a, b)
    local sep = package.config:sub(1,1) -- Detects OS-specific path separator
    if a:sub(-1) ~= sep then
        a = a .. sep
    end
    return a .. b
end

---Return full path for a file inside src/.
---@param filename string
---@return string
function pkg.src_path(filename)
    return pkg.join(pkg.src_dir, filename)
end

--[[
    EXAMPLE USAGE
    ---------------------------------------------------------------------------
    local pkg = require("pkg-workfile")
    print("Root:", pkg.root_dir)
    print("API Key:", pkg.API_KEY)
    print("Main script:", pkg.src_path("main.lua"))
]]

-- Export the configuration table
return pkg
