feat: strengthen validation logic and redesign data structure of internal state

- refactor: enforce convention - all side effect variables must be written in UPPERCASE
- chore: add custom Git hooks for automatic testing before remote pushing

Author: vhbui02

.gitignore

@@ -37,6 +37,5 @@ temp/
 
 # Misc
 node_modules
-hooks
 .memory-bank/
 memory-bank/

.gitmodules

@@ -22,7 +22,7 @@ Licensed under [BSD 3-Clause License](LICENSE).
 ## Features
 
 -   **Zero dependencies:** All code is original and thoroughly audited by the author.
--   **Options as the SSOT:** No positional arguments or subcommands—simplicity is prioritized.
+-   **Options-only design:** No positional arguments or subcommands—options are the single source of truth, prioritizing simplicity.
 -   **Structured option handling:** Options are defined with clear metadata, allowing reliable registration, parsing, and validation.
 -   **Multi-level, color-coded logging:** Output messages at five levels (Debug, Info, Warning, Error, Critical) with color support.
 -   **Reliable locking mechanism:** Prevents concurrent script execution.
@@ -194,7 +194,7 @@ main "$@"
 
 ## Design Decisions
 
--   **Option-only approach:** No subcommands or positional arguments. Simplicity takes precedence.
+-   **Options-only approach:** This template is designed to handle options exclusively—no subcommands or positional arguments. For complex multi-command CLIs, use mature frameworks like Click (Python), Cobra (Go), or similar tools that are battle-tested for subcommand handling.
 -   **Conservative default syntax** (e.g. `${param:-}`): Use only for **optional arguments** and explicit exceptions. **AVOID overusing on every variable.**
 -   **Fail-fast philosophy:**
     -   Enable `set -e` to terminate the script when undefined variables are referenced unexpectedly.

README.md

@@ -3,22 +3,36 @@
 # ============================================================================ #
 
 ## FILE         : build.sh
-## VERSION      : v3.0.0
+## VERSION      : 1.0.0
 ## DESCRIPTION  : Merge source and script into template
 ## AUTHOR       : silverbullet069
 ## REPOSITORY   : https://github.com/Silverbullet069/bash-script-template
 ## LICENSE      : BSD-3-Clause
 
-## TEMREPO      : https://github.com/Silverbullet069/bash-script-template
-## TEMMODE      : lite
-## TEMVER       : v3.0.0
-## TEMUPDATED   : 2025-06-21 19:15:03.788041997 +0700
-## TEMLIC       : BSD-3-Clause
-
 # ============================================================================ #
 
+# DESC: An 'echo' wrapper that redirects standard output to standard error
+# ARGS: $@ (required): Message(s) to echo
+# OUTS: None
+# RETS: None
+function log() {
+    echo "$@" >&2
+}
+
+# FUNCTION: check_binary
+# DESC: Checks if a given binary/command is available in the system's PATH.
+# ARGS: $1 (required): Name of the binary/command to check.
+# OUTS: Prints an error message to stderr if the binary is missing.
+# RETS: Returns 1 if the binary is missing, 0 otherwise.
+function check_binary() {
+    if ! command -v "$1" >/dev/null 2>&1; then
+        log "Missing dependency '$1'"
+        return 1
+    fi
+}
+
 # DESC: Acquire script lock, extracted from script.sh
-# ARGS: $1 (optional): Scope of script execution lock (system or user)
+# ARGS: $1 (required): Scope of script execution lock (system or user)
 # OUTS: None
 # RETS: None
 # NOTE: This lock implementation is extremely simple but should be reliable
@@ -32,15 +46,15 @@ function lock_init() {
     elif [[ "${1}" = "user" ]]; then
         lock_dir="/tmp/$(basename "${BASH_SOURCE[0]}").${UID}.lock"
     else
-        echo "Missing or invalid argument to ${FUNCNAME[0]}()!" >&2
+        log "Missing or invalid argument to ${FUNCNAME[0]}()!"
         exit 1
     fi
 
     if mkdir "${lock_dir}" 2>/dev/null; then
         readonly script_lock="${lock_dir}"
-        echo "Acquired script lock: ${script_lock}"
+        log "Acquired script lock: ${script_lock}"
     else
-        echo "Unable to acquire script lock: ${lock_dir}" >&2
+        log "Unable to acquire script lock: ${lock_dir}"
         exit 2
     fi
 }
@@ -53,7 +67,7 @@ function script_trap_exit() {
     # Remove script execution lock
     if [[ -d "${script_lock-}" ]]; then
         rmdir "${script_lock}"
-        echo "Clean up script lock: ${script_lock}" >&2
+        log "Clean up script lock: ${script_lock}"
     fi
 }
 
@@ -76,22 +90,22 @@ function build() {
     local -r template_path="${3}"
 
     if [[ ! -f "${source_path}" ]]; then
-        echo "source.sh not found: ${script_path}" >&2
+        log "source.sh not found: ${script_path}"
         exit 1
     fi
 
     if [[ ! -r "${source_path}" ]]; then
-        echo "source.sh is unreadable: ${script_path}" >&2
+        log "source.sh is unreadable: ${script_path}"
         exit 1
     fi
 
     if [[ ! -f "${script_path}" ]]; then
-        echo "script.sh not found: ${script_path}" >&2
+        log "script.sh not found: ${script_path}"
         exit 1
     fi
 
     if [[ ! -r "${script_path}" ]]; then
-        echo "script.sh is unreadable: ${script_path}" >&2
+        log "script.sh is unreadable: ${script_path}"
         exit 1
     fi
 
@@ -100,19 +114,22 @@ function build() {
     local -r source_body=$(tail -n +12 "${source_path}")
     local -r script_body=$(tail -n +19 "${script_path}" | grep -vE -e '^# shellcheck source=source.sh$' -e '^# shellcheck disable=SC1091$' -e '^source.*source\.sh"$')
 
+    # temporily make it writeable
     chmod 755 "${template_path}"
     {
-        echo "${script_header}"
-        echo "${source_body}"
-        echo "${script_body}"
-    } >"${template_path}"
+        log "${script_header}"
+        log "${source_body}"
+        log "${script_body}"
+    } 2>"${template_path}"
 
+    # then, make it read-only
     chmod 555 "${template_path}"
-    echo "Build ${template_path} successfully."
+
+    log "Build ${template_path} successfully."
 }
 
 function cleanup() {
-    echo "Stopping file monitor..."
+    log "Stopping file monitor..."
     exit 0
 }
 
@@ -138,7 +155,7 @@ function main() {
             --event "close_write" \
             "${source_path}" "${script_path}" \
             | while read -r dir event file; do
-                echo "Change detected: ${event} on ${dir}${file}"
+                log "Change detected: ${event} on ${dir}${file}"
                 # NOTE: add a small delay to allow accumulation of multiple changes
                 sleep 1
                 build "${source_path}" "${script_path}" "${template_path}"

build.sh

@@ -3,16 +3,14 @@
 # ============================================================================ #
 
 ## FILE         : clone.sh
-## VERSION      : v3.0.0
+## VERSION      : 1.0.0
 ## DESCRIPTION  : Clone specific template into specific output
 ## AUTHOR       : silverbullet069
 ## REPOSITORY   : https://github.com/Silverbullet069/bash-script-template
 ## LICENSE      : BSD 3-Clause License
 
 ## TEMREPO      : https://github.com/Silverbullet069/bash-script-template
-## TEMMODE      : src
-## TEMVER       : v3.0.0
-## TEMUPDATED   : 2025-07-09 02:22:09.981519546 +0700
+## TEMAUTHOR    : Silverbullet069
 ## TEMLIC       : BSD 3-Clause License
 
 # ============================================================================ #
@@ -24,16 +22,30 @@
 # OUTS: SCRIPT_PARSED_VALUES populated with parsed parameters
 # RETS: 0
 function option_init() {
-    # NOTE: the order: long-name, short-name, default, help, type, required, constraints
-    register_option "--mode" "-m" "lite" "Template mode" "choice" true "full,lite,legacy,src"
-    register_option "--output" "-o" "${PWD}/temp.sh" "Output file path" "path"
-    register_option "--yes" "-y" false "Skip prompting for metadata" "bool"
-
-    register_option "--help" "-h" false "Display this help and exit" "bool"
-    register_option "--log-level" "-l" "INF" "Specify log level" "choice" false "DBG,INF,WRN,ERR"
-    register_option "--timestamp" "-t" false "Enable timestamp output" "bool"
-    register_option "--no-color" "-n" false "Disable color output" "bool"
-    register_option "--quiet" "-q" false "Run silently unless an error is encountered" "bool"
+    register_builtin_options
+
+    register_option \
+        --long "--mode" \
+        --short "-m" \
+        --type "choice" \
+        --default "lite" \
+        --required "true" \
+        --constraints "full,lite,legacy,src"\
+        --help "Template mode"
+
+    register_option \
+        --long "--output" \
+        --short "-o" \
+        --type "path" \
+        --default "${PWD}/temp.sh" \
+        --help "Output file path"
+
+    register_option \
+        --long "--yes" \
+        --short "-y" \
+        --type "bool" \
+        --default "false" \
+        --help "Skip prompting for metadata"
 }
 
 function print_help_message() {
@@ -53,7 +65,7 @@ To create a 'full' template with custom output destination:
 
     clone -m full -o path/to/script.bash
 
-By default, the script will prompt for information to be placed inside the 
+By default, the script will prompt for information to be placed inside the
 header. To skip prompting:
 
     clone -y ...
@@ -82,15 +94,15 @@ function main() {
     local -r mode="${VALUES["--mode"]}"
     local file=
     case "${mode}" in
+        legacy)
+            file="template_legacy.sh"
+            ;;
         full)
             file="template.sh"
             ;;
         lite)
             file="template_lite.sh"
             ;;
-        legacy)
-            file="template_legacy.sh"
-            ;;
         src)
             file="script.sh"
             ;;
@@ -102,7 +114,7 @@ function main() {
 
     # Source path initialization
     # shellcheck disable=SC2154
-    local -r src="${script_dir}/${file}"
+    local -r src="${SCRIPT_DIR}/${file}"
     if [[ ! -f "${src}" ]]; then
         script_exit "${src} not found."
     fi
@@ -157,7 +169,7 @@ function main() {
 
     # add value to template-related placeholders
     local -r updated="$(stat -c "%y" "${src}" 2>/dev/null)"
-    local -r tag="$(ls -t "${script_dir}/.git/refs/tags" | head -n1)"
+    local -r tag="$(ls -t "${SCRIPT_DIR}/.git/refs/tags" | head -n1)"
 
     # Replace placeholders in the cloned file
     if ! sed -i \
@@ -175,7 +187,7 @@ function main() {
     fi
 
     if [[ "${mode}" == "src" ]]; then
-        local -r path="${script_dir}/source.sh"
+        local -r path="${SCRIPT_DIR}/source.sh"
         if [[ ! -f "${path}" ]]; then
             script_exit "${path} not found"
         fi

clone.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+./test.sh "tests"
+if [[ $? -ne 0 ]]; then
+    echo "BATS tests failed. Push aborted."
+    exit 1
+fi

hooks/pre-push

@@ -17,21 +17,20 @@
 
 # ============================================================================ #
 
+# ============================================================================ #
+# CUSTOM LOGIC                                                                 #
+# ============================================================================ #
+
 # DESC: Register the a set of options
 # ARGS: None
-# OUTS: OPTIONS, ORDERS and VALUES are populated with data
+# OUTS: OPTIONS, ORDERS and VALUES data are populated
 # RETS: 0
 function option_init() {
-    # NOTE: long-name, short-name, default, help, type, required, constraints
-    # register_option ...
-
-    # CAUTION: --help must be placed as the first option in the built-in options list
-    # CAUTION: I add a blank link on top of this function inside help message
-    register_option "--help" "-h" false "Display this help and exit" "bool"
-    register_option "--log-level" "-l" "INF" "Specify log level" "choice" false "DBG,INF,WRN,ERR"
-    register_option "--timestamp" "-t" false "Enable timestamp output" "bool"
-    register_option "--no-color" "-n" false "Disable color output" "bool"
-    register_option "--quiet" "-q" false "Run silently unless an error is encountered" "bool"
+    # --help, --log-level, --timestamp, --no-color, --quiet
+    register_builtin_options
+
+    # Custom options
+    # ...
 }
 
 # DESC: Print help message when user declare --help, -h option
@@ -56,6 +55,10 @@ EOF
 
 }
 
+# ============================================================================ #
+# MAIN CONTROL FLOW                                                            #
+# ============================================================================ #
+
 # DESC: Main control flow
 # ARGS: $@ (optional): Arguments provided to the script
 # OUTS: None
@@ -72,24 +75,35 @@ function main() {
     lock_init user
 
     # start here
-    # shellcheck disable=SC2154
-    debug "script_params: ${script_params}"
-    # shellcheck disable=SC2154
-    debug "script_path: ${script_path}"
-    # shellcheck disable=SC2154
-    debug "script_dir: ${script_dir}"
-    # shellcheck disable=SC2154
-    debug "script_name: ${script_name}"
+    # ...
 
     # Logging helper functions
     error "This is an error message"
     warn "This is a warning message"
     info "This is an info message"
     debug "This is a debug message"
+
+    # Logging internal states
+    debug "SCRIPT_NAME: ${SCRIPT_NAME}"
+    debug "SCRIPT_PATH: ${SCRIPT_PATH}"
+    debug "SCRIPT_DIR: ${SCRIPT_DIR}"
+    debug "SCRIPT_PARAMS: ${SCRIPT_PARAMS}"
+
+    debug "Registered options: ${ORDERS[*]}"
+    debug "Parsed values:"
+    for key in "${!VALUES[@]}"; do
+        debug "  ${key} = '${VALUES[$key]}'"
+    done
+    debug "OPTION_SHORT:" "${OPTION_SHORT[@]}"
+    debug "OPTION_DEFAULT:" "${OPTION_DEFAULT[@]}"
+    debug "OPTION_TYPE:" "${OPTION_TYPE[@]}"
+    debug "OPTION_REQUIRED:" "${OPTION_REQUIRED[@]}"
+    debug "OPTION_CONSTRAINTS:" "${OPTION_CONSTRAINTS[@]}"
+    debug "OPTION_HELP:" "${OPTION_HELP[@]}"
 }
 
 # ============================================================================ #
-# Helper flags
+# SCRIPT INITIALIZATION FLAGS                                                  #
 # ============================================================================ #
 
 # Enable xtrace if the DEBUG environment variable is set