scripts/ENTERPRISE.md

@@ -0,0 +1,526 @@
+<!-- Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+
+This file is part of a Moko Consulting project.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU 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 General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see https://www.gnu.org/licenses/ .
+
+FILE INFORMATION
+DEFGROUP: Moko-Cassiopeia.Documentation
+INGROUP: Scripts.Documentation
+REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+FILE: ./scripts/ENTERPRISE.md
+VERSION: 01.00.00
+BRIEF: Enterprise-grade scripting standards and best practices
+-->
+
+# Enterprise Standards for Scripts
+
+This document defines the enterprise-grade standards and best practices
+implemented across all automation scripts in this repository.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Core Principles](#core-principles)
+- [Script Structure](#script-structure)
+- [Error Handling](#error-handling)
+- [Logging and Observability](#logging-and-observability)
+- [Security Standards](#security-standards)
+- [Dependency Management](#dependency-management)
+- [Exit Codes](#exit-codes)
+- [Documentation Requirements](#documentation-requirements)
+- [Testing and Validation](#testing-and-validation)
+- [Operational Considerations](#operational-considerations)
+
+## Overview
+
+All scripts in this repository follow enterprise-grade standards to ensure:
+- **Reliability**: Predictable behavior in all environments
+- **Security**: Protection against vulnerabilities and credential exposure
+- **Observability**: Clear logging and error reporting
+- **Maintainability**: Consistent patterns and documentation
+- **Portability**: Cross-platform compatibility
+
+## Core Principles
+
+### 1. Fail Fast, Fail Clearly
+
+Scripts must fail immediately when encountering errors and provide clear,
+actionable error messages.
+
+```bash
+set -euo pipefail  # Required at top of all bash scripts
+```
+
+- `-e`: Exit on first error
+- `-u`: Exit on undefined variable reference
+- `-o pipefail`: Propagate pipeline failures
+
+### 2. Zero Assumptions
+
+- Always validate inputs
+- Check for required dependencies
+- Verify file/directory existence before access
+- Never assume environment state
+
+### 3. Idempotency Where Possible
+
+Scripts should be safe to run multiple times without causing harm or
+inconsistency.
+
+### 4. Least Privilege
+
+Scripts should:
+- Never require root unless absolutely necessary
+- Use minimal file system permissions
+- Validate before modifying files
+
+## Script Structure
+
+### Standard Header Template
+
+Every script must include:
+
+```bash
+#!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# [Full license text...]
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Category
+# INGROUP: Subcategory
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/path/to/script.sh
+# VERSION: XX.XX.XX
+# BRIEF: One-line description of script purpose
+# NOTE: Additional context or usage notes
+# ============================================================================
+
+set -euo pipefail
+```
+
+### Usage Function
+
+User-facing scripts must provide a usage/help function:
+
+```bash
+usage() {
+cat <<-USAGE
+Usage: $0 [OPTIONS] <ARGS>
+
+Description of what the script does.
+
+Options:
+  -h, --help    Show this help message
+  -v, --verbose Enable verbose output
+
+Arguments:
+  ARG1    Description of first argument
+  ARG2    Description of second argument
+
+Examples:
+  $0 example_value
+  $0 -v example_value
+
+Exit codes:
+  0 - Success
+  1 - Error
+  2 - Invalid arguments
+
+USAGE
+exit 0
+}
+```
+
+### Argument Parsing
+
+```bash
+# Parse arguments
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+    usage
+fi
+
+[ $# -ge 1 ] || usage
+```
+
+### Library Sourcing
+
+```bash
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+. "${SCRIPT_DIR}/lib/common.sh"
+
+# Check dependencies
+check_dependencies python3 git
+```
+
+## Error Handling
+
+### Error Messages
+
+Error messages must be:
+- **Clear**: Explain what went wrong
+- **Actionable**: Tell user how to fix it
+- **Contextual**: Include relevant details
+
+```bash
+# Bad
+die "Error"
+
+# Good
+die "Required file not found: ${CONFIG_FILE}. Run setup first."
+```
+
+### Validation
+
+```bash
+# Validate inputs
+validate_version() {
+    local v="$1"
+    if ! printf '%s' "$v" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+        die "Invalid version format: $v (expected X.Y.Z)"
+    fi
+}
+
+# Check file existence
+assert_file_exists "${MANIFEST}" || die "Manifest not found: ${MANIFEST}"
+
+# Verify directory
+assert_dir_exists "${SRC_DIR}" || die "Source directory missing: ${SRC_DIR}"
+```
+
+## Logging and Observability
+
+### Logging Functions
+
+Use standard logging functions from `lib/common.sh`:
+
+```bash
+log_info "Starting process..."      # Informational messages
+log_warn "Configuration missing"    # Warnings (non-fatal)
+log_error "Validation failed"       # Errors (fatal)
+die "Critical error occurred"       # Fatal with exit
+```
+
+### Timestamps
+
+Include timestamps for audit trails:
+
+```bash
+log_info "Start time: $(log_timestamp)"
+# ... work ...
+log_info "End time: $(log_timestamp)"
+```
+
+### Structured Output
+
+For machine-readable output, use JSON:
+
+```bash
+printf '{"status":"ok","files_checked":%s}\n' "${count}"
+```
+
+### Progress Reporting
+
+For long-running operations:
+
+```bash
+log_section "Phase 1: Validation"
+log_step "Checking manifests..."
+log_success "✓ Manifests valid"
+log_kv "Files processed" "${count}"
+```
+
+## Security Standards
+
+### 1. No Hardcoded Secrets
+
+- Never commit credentials
+- Use environment variables for sensitive data
+- Validate against secret patterns
+
+### 2. Input Sanitization
+
+```bash
+# Validate user input
+if [[ "${input}" =~ [^a-zA-Z0-9._-] ]]; then
+    die "Invalid input: contains disallowed characters"
+fi
+```
+
+### 3. File Operations
+
+```bash
+# Use explicit paths
+FILE="/full/path/to/file"
+
+# Avoid user-controlled paths without validation
+# Validate before rm/mv operations
+```
+
+### 4. Command Injection Prevention
+
+```bash
+# Use arrays for command arguments
+args=("$file1" "$file2")
+command "${args[@]}"
+
+# Quote all variables
+grep "${pattern}" "${file}"
+```
+
+## Dependency Management
+
+### Required Dependencies Check
+
+```bash
+# At script start
+check_dependencies python3 git sed
+
+# Or inline
+require_cmd xmllint || die "xmllint not available"
+```
+
+### Graceful Degradation
+
+When optional dependencies are missing:
+
+```bash
+if ! command -v php >/dev/null 2>&1; then
+    log_warn "PHP not available, skipping syntax check"
+    exit 0
+fi
+```
+
+## Exit Codes
+
+Standard exit codes across all scripts:
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 0 | Success | All operations completed successfully |
+| 1 | Error | Fatal error occurred |
+| 2 | Invalid arguments | Bad command-line arguments or usage |
+
+```bash
+# Success
+exit 0
+
+# Fatal error
+die "Error message"  # Exits with code 1
+
+# Invalid arguments
+usage  # Exits with code 0 (help shown)
+# or
+log_error "Invalid argument"
+exit 2
+```
+
+## Documentation Requirements
+
+### 1. Script Headers
+
+Must include:
+- Copyright notice
+- SPDX license identifier
+- FILE INFORMATION section
+- Version number
+- Brief description
+
+### 2. Inline Comments
+
+Use comments for:
+- Complex logic explanation
+- Why decisions were made (not what code does)
+- Security considerations
+- Performance notes
+
+```bash
+# Use git ls-files for performance vs. find
+files=$(git ls-files '*.yml' '*.yaml')
+
+# NOTE: Binary detection prevents corrupting image files
+if file --mime-type "$f" | grep -q '^application/'; then
+    continue
+fi
+```
+
+### 3. README Documentation
+
+Update `scripts/README.md` when:
+- Adding new scripts
+- Changing script behavior
+- Adding new library functions
+
+## Testing and Validation
+
+### Self-Testing
+
+Scripts should validate their own requirements:
+
+```bash
+# Validate environment
+[ -d "${SRC_DIR}" ] || die "Source directory not found"
+
+# Validate configuration
+[ -n "${VERSION}" ] || die "VERSION must be set"
+```
+
+### Integration Testing
+
+Run validation suite before commits:
+
+```bash
+./scripts/run/validate_all.sh
+```
+
+### Smoke Testing
+
+Basic health checks:
+
+```bash
+./scripts/run/smoke_test.sh
+```
+
+## Operational Considerations
+
+### 1. Timeout Handling
+
+For long-running operations:
+
+```bash
+run_with_timeout 300 long_running_command
+```
+
+### 2. Cleanup
+
+Use traps for cleanup:
+
+```bash
+cleanup() {
+    rm -f "${TEMP_FILE}"
+}
+trap cleanup EXIT
+```
+
+### 3. Lock Files
+
+For singleton operations:
+
+```bash
+LOCK_FILE="/tmp/script.lock"
+if [ -f "${LOCK_FILE}" ]; then
+    die "Script already running (lock file exists)"
+fi
+touch "${LOCK_FILE}"
+trap "rm -f ${LOCK_FILE}" EXIT
+```
+
+### 4. Signal Handling
+
+```bash
+handle_interrupt() {
+    log_warn "Interrupted by user"
+    cleanup
+    exit 130
+}
+trap handle_interrupt INT TERM
+```
+
+### 5. Dry Run Mode
+
+For destructive operations:
+
+```bash
+DRY_RUN="${DRY_RUN:-false}"
+
+if [ "${DRY_RUN}" = "true" ]; then
+    log_info "DRY RUN: Would execute: $command"
+else
+    "$command"
+fi
+```
+
+## CI/CD Integration
+
+### Environment Variables
+
+Scripts should respect:
+
+```bash
+CI="${CI:-false}"              # Running in CI
+VERBOSE="${VERBOSE:-false}"    # Verbose output
+DEBUG="${DEBUG:-false}"        # Debug mode
+```
+
+### CI-Specific Behavior
+
+```bash
+if is_ci; then
+    # CI-specific settings
+    set -x  # Echo commands for debugging
+fi
+```
+
+### Job Summaries
+
+For GitHub Actions:
+
+```bash
+if [ -n "${GITHUB_STEP_SUMMARY:-}" ]; then
+    echo "### Validation Results" >> "$GITHUB_STEP_SUMMARY"
+    echo "Status: PASSED" >> "$GITHUB_STEP_SUMMARY"
+fi
+```
+
+## Review Checklist
+
+Before committing new or modified scripts:
+
+- [ ] Includes proper copyright header
+- [ ] Uses `set -euo pipefail`
+- [ ] Has usage/help function (if user-facing)
+- [ ] Validates all inputs
+- [ ] Checks dependencies
+- [ ] Uses structured logging
+- [ ] Returns appropriate exit codes
+- [ ] Includes inline comments for complex logic
+- [ ] Documented in scripts/README.md
+- [ ] Tested locally
+- [ ] Passes `shellcheck` (if available)
+- [ ] Passes all validation checks
+
+## Version History
+
+| Version | Date       | Description |
+| ------- | ---------- | ----------- |
+| 01.00.00 | 2025-01-03 | Initial enterprise standards documentation |
+
+## Metadata
+
+- **Document:** scripts/ENTERPRISE.md
+- **Repository:** https://github.com/mokoconsulting-tech/moko-cassiopeia
+- **Version:** 01.00.00
+- **Status:** Active

scripts/README.md

@@ -255,6 +255,18 @@ WARN: ✗ tabs (warnings/issues found - run with -v for details)
 
 ## Best Practices
 
+### Enterprise Standards
+
+For comprehensive enterprise-grade scripting standards, see
+[ENTERPRISE.md](./ENTERPRISE.md).
+
+Key highlights:
+- **Error Handling**: Fail fast with clear, actionable messages
+- **Security**: Input validation, no hardcoded secrets
+- **Logging**: Structured output with timestamps
+- **Portability**: Cross-platform compatibility
+- **Documentation**: Usage functions and inline comments
+
 ### Writing New Scripts
 
 1. **Use the library functions**:
@@ -313,6 +325,51 @@ Scripts are automatically executed in GitHub Actions workflows:
 - `.github/workflows/ci.yml` - Continuous integration
 - `.github/workflows/repo_health.yml` - Repository health checks
 
+## Enterprise Features
+
+The scripts in this repository follow enterprise-grade standards:
+
+### Dependency Checking
+
+Scripts validate required dependencies at startup using `check_dependencies`:
+
+```bash
+check_dependencies python3 git sed
+```
+
+### Timestamp Logging
+
+All major operations include timestamps for audit trails:
+
+```bash
+log_info "Start time: $(log_timestamp)"
+```
+
+### Usage Documentation
+
+All user-facing scripts include comprehensive help:
+
+```bash
+./scripts/run/validate_all.sh --help
+./scripts/fix/versions.sh --help
+```
+
+### Standardized Exit Codes
+
+- `0` - Success
+- `1` - Fatal error
+- `2` - Invalid arguments
+
+### Enhanced Error Messages
+
+Clear, actionable error messages with context:
+
+```bash
+die "Required file not found: ${CONFIG_FILE}. Run setup first."
+```
+
+See [ENTERPRISE.md](./ENTERPRISE.md) for complete standards documentation.
+
 ## Version History
 
 | Version | Date       | Description                           |

scripts/fix/versions.sh

@@ -54,8 +54,19 @@ Arguments:
 Examples:
   $0 3.5.0
   $0 1.2.3
+
+Exit codes:
+  0 - Version updated successfully
+  1 - Invalid version format or update failed
+  2 - Invalid arguments
+
+Files updated:
+  - Joomla manifest XML (<version> tag)
+  - package.json (if present)
+  - README.md (VERSION: references, if present)
+
 USAGE
-exit 1
+exit 0
 }
 
 validate_version() {
@@ -69,12 +80,21 @@ fi
 # Main
 # ----------------------------------------------------------------------------
 
+# Parse arguments
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+	usage
+fi
+
 [ $# -eq 1 ] || usage
 
 VERSION="$1"
 validate_version "${VERSION}"
 
+# Check dependencies
+check_dependencies python3
+
 log_info "Updating version to: ${VERSION}"
+log_info "Start time: $(log_timestamp)"
 
 # Source Joomla manifest utilities
 . "${SCRIPT_DIR}/lib/joomla_manifest.sh"
@@ -149,6 +169,7 @@ fi
 
 log_info "========================================="
 log_info "Version update completed: ${VERSION}"
+log_info "End time: $(log_timestamp)"
 log_info "Files updated:"
 log_info "  - ${MANIFEST}"
 [ -f "package.json" ] && log_info "  - package.json"

scripts/lib/common.sh

@@ -136,3 +136,37 @@ PY
 fail_if_root() {
 	[ "$(id -u)" -eq 0 ] && die "Script must not run as root"
 }
+
+# ----------------------------------------------------------------------------
+# Enterprise features
+# ----------------------------------------------------------------------------
+
+# Check for required dependencies at script start
+check_dependencies() {
+	local missing=0
+	for cmd in "$@"; do
+		if ! command -v "$cmd" >/dev/null 2>&1; then
+			log_error "Required command not found: $cmd"
+			missing=$((missing + 1))
+		fi
+	done
+	[ "$missing" -eq 0 ] || die "Missing $missing required command(s)"
+}
+
+# Timeout wrapper for long-running commands
+run_with_timeout() {
+	local timeout="$1"
+	shift
+	if command -v timeout >/dev/null 2>&1; then
+		timeout "$timeout" "$@"
+	else
+		"$@"
+	fi
+}
+
+# Add script execution timestamp
+log_timestamp() {
+	if command -v date >/dev/null 2>&1; then
+		printf '%s\n' "$(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+	fi
+}

scripts/run/smoke_test.sh

@@ -35,11 +35,41 @@
 
 set -euo pipefail
 
+# ----------------------------------------------------------------------------
+# Usage
+# ----------------------------------------------------------------------------
+
+usage() {
+cat <<-USAGE
+Usage: $0 [OPTIONS]
+
+Run basic smoke tests to verify repository structure and manifest validity.
+
+Options:
+  -h, --help    Show this help message
+
+Examples:
+  $0              # Run all smoke tests
+  $0 --help       # Show usage information
+
+USAGE
+exit 0
+}
+
+# Parse arguments
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
+	usage
+fi
+
 # Source common utilities
 SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 . "${SCRIPT_DIR}/lib/common.sh"
 
+# Check dependencies
+check_dependencies python3
+
 log_info "Running smoke tests for Moko-Cassiopeia repository"
+log_info "Start time: $(log_timestamp)"
 
 # ----------------------------------------------------------------------------
 # Test: Repository structure
@@ -143,4 +173,5 @@ log_info "Smoke tests completed successfully"
 log_info "Extension: ${NAME}"
 log_info "Version: ${VERSION}"
 log_info "Type: ${TYPE}"
+log_info "End time: $(log_timestamp)"
 log_info "========================================="

scripts/run/validate_all.sh

@@ -39,16 +39,63 @@ SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 . "${SCRIPT_DIR}/lib/common.sh"
 . "${SCRIPT_DIR}/lib/logging.sh"
 
+# ----------------------------------------------------------------------------
+# Usage
+# ----------------------------------------------------------------------------
+
+usage() {
+cat <<-USAGE
+Usage: $0 [OPTIONS]
+
+Run all validation scripts and report results.
+
+Options:
+  -v, --verbose    Show detailed output from validation scripts
+  -h, --help       Show this help message
+
+Examples:
+  $0              # Run all validations in quiet mode
+  $0 -v           # Run with verbose output
+  $0 --help       # Show usage information
+
+Exit codes:
+  0 - All required checks passed
+  1 - One or more required checks failed
+  2 - Invalid arguments
+
+USAGE
+exit 0
+}
+
 # ----------------------------------------------------------------------------
 # Configuration
 # ----------------------------------------------------------------------------
 
 VERBOSE="${1:-}"
-if [ "${VERBOSE}" = "-v" ] || [ "${VERBOSE}" = "--verbose" ]; then
+
+# Parse arguments
+case "${VERBOSE}" in
+	-h|--help)
+		usage
+		;;
+	-v|--verbose)
 		VERBOSE="true"
-else
+		;;
+	"")
 		VERBOSE="false"
-fi
+		;;
+	*)
+		log_error "Invalid argument: ${VERBOSE}"
+		echo ""
+		usage
+		exit 2
+		;;
+esac
+
+# Check dependencies
+check_dependencies python3
+
+log_info "Start time: $(log_timestamp)"
 
 REQUIRED_CHECKS=(
 	"manifest"
@@ -156,6 +203,8 @@ log_kv "Optional checks with issues" "${optional_failed}"
 
 log_separator
 
+log_info "End time: $(log_timestamp)"
+
 if [ "${required_failed}" -gt 0 ]; then
 	log_error "FAILED: ${required_failed} required check(s) failed"
 	exit 1

scripts/validate/changelog.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Documentation
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/changelog.sh
+# VERSION: 01.00.00
+# BRIEF: Validates CHANGELOG.md structure and version entries
+# NOTE: Ensures changelog compliance with Keep a Changelog standard
+# ============================================================================
+
 set -euo pipefail
 
 json_escape() {

scripts/validate/language_structure.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Joomla.Language
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/language_structure.sh
+# VERSION: 01.00.00
+# BRIEF: Validates Joomla language directory structure and INI files
+# NOTE: Ensures proper language file organization
+# ============================================================================
+
 set -euo pipefail
 
 SRC_DIR="${SRC_DIR:-src}"

scripts/validate/license_headers.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Licensing
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/license_headers.sh
+# VERSION: 01.00.00
+# BRIEF: Checks that source files contain SPDX license identifiers
+# NOTE: Ensures licensing compliance across codebase
+# ============================================================================
+
 set -euo pipefail
 
 SRC_DIR="${SRC_DIR:-src}"

scripts/validate/manifest.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Joomla.Manifest
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/manifest.sh
+# VERSION: 01.00.00
+# BRIEF: Validates Joomla manifest XML structure and required fields
+# NOTE: Ensures extension manifest compliance
+# ============================================================================
+
 set -euo pipefail
 
 log() { printf '%s\n' "$*"; }

scripts/validate/no_secrets.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Security
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/no_secrets.sh
+# VERSION: 01.00.00
+# BRIEF: Scan for accidentally committed secrets and credentials
+# NOTE: High-signal pattern detection to prevent credential exposure
+# ============================================================================
+
 set -euo pipefail
 
 SRC_DIR="${SRC_DIR:-src}"

scripts/validate/paths.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Path.Normalization
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/paths.sh
+# VERSION: 01.00.00
+# BRIEF: Detect Windows-style path separators (backslashes)
+# NOTE: Ensures cross-platform path compatibility
+# ============================================================================
+
 set -euo pipefail
 
 # Detect Windows-style path literals (backslashes) in repository files.

scripts/validate/php_syntax.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Code.Quality
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/php_syntax.sh
+# VERSION: 01.00.00
+# BRIEF: Validates PHP syntax using php -l on all PHP files
+# NOTE: Requires PHP CLI to be available
+# ============================================================================
+
 set -euo pipefail
 
 SRC_DIR="${SRC_DIR:-src}"

scripts/validate/tabs.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Code.Quality
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/tabs.sh
+# VERSION: 01.00.00
+# BRIEF: Detect TAB characters in YAML files where they are not allowed
+# NOTE: YAML specification forbids tab characters
+# ============================================================================
+
 set -euo pipefail
 
 # Detect TAB characters in source files tracked by Git. Uses careful

scripts/validate/version_alignment.sh

@@ -1,4 +1,38 @@
 #!/usr/bin/env bash
+
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: Version.Management
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/version_alignment.sh
+# VERSION: 01.00.00
+# BRIEF: Checks that manifest version is documented in CHANGELOG.md
+# NOTE: Ensures version consistency across repository
+# ============================================================================
+
 set -euo pipefail
 
 # Validate that the package/manifest version is present in CHANGELOG.md

scripts/validate/xml_wellformed.sh

@@ -1,5 +1,38 @@
 #!/usr/bin/env bash
 
+# ============================================================================
+# Copyright (C) 2025 Moko Consulting <hello@mokoconsulting.tech>
+#
+# This file is part of a Moko Consulting project.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU 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 General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program (./LICENSE.md).
+# ============================================================================
+
+# ============================================================================
+# FILE INFORMATION
+# ============================================================================
+# DEFGROUP: Script.Validate
+# INGROUP: XML.Validation
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/validate/xml_wellformed.sh
+# VERSION: 01.00.00
+# BRIEF: Validates that all XML files are well-formed
+# NOTE: Uses Python ElementTree for portable XML parsing
+# ============================================================================
+
 set -euo pipefail
 
 SRC_DIR="${SRC_DIR:-src}"