MokoCassiopeia/scripts

Scripts Directory

This directory contains automation scripts for repository management, validation, and release processes for the Moko-Cassiopeia Joomla template.

Directory Structure

scripts/
├── fix/           # Scripts that automatically fix common issues
├── lib/           # Shared library functions
├── release/       # Release automation scripts
├── run/           # Execution and testing scripts
└── validate/      # Validation and linting scripts

Library Files (lib/)

common.sh

Core utilities used by all scripts:

• Environment normalization
• Logging functions (log_info, log_warn, log_error, die)
• Validation helpers (assert_file_exists, assert_dir_exists)
• JSON utilities (json_escape, json_output)
• Path helpers (script_root, normalize_path)

Usage:

. "$(dirname "$0")/../lib/common.sh"
log_info "Starting process..."

joomla_manifest.sh

Joomla manifest parsing utilities:

• find_manifest <src_dir> - Find primary Joomla manifest XML
• get_manifest_version <manifest> - Extract version from manifest
• get_manifest_name <manifest> - Extract extension name
• get_manifest_type <manifest> - Extract extension type

Usage:

. "${SCRIPT_DIR}/lib/joomla_manifest.sh"
MANIFEST="$(find_manifest src)"
VERSION="$(get_manifest_version "${MANIFEST}")"

logging.sh

Enhanced logging with structured output:

• Colored output support (when in terminal)
• Log levels: log_debug, log_success, log_step
• Structured logging: log_kv, log_item, log_section

Usage:

. "${SCRIPT_DIR}/lib/logging.sh"
log_section "Starting validation"
log_kv "Version" "${VERSION}"
log_success "All checks passed"

Validation Scripts (validate/)

These scripts validate repository structure, code quality, and compliance. They are typically run in CI pipelines.

manifest.sh

Validates Joomla manifest XML structure and required fields.

version_alignment.sh

Checks that manifest version is documented in CHANGELOG.md.

php_syntax.sh

Validates PHP syntax using php -l on all PHP files.

xml_wellformed.sh

Validates that all XML files are well-formed.

tabs.sh

Detects tab characters in source files (enforces spaces).

paths.sh

Detects Windows-style path separators (backslashes).

no_secrets.sh

Scans for accidentally committed secrets and credentials.

license_headers.sh

Checks that source files contain SPDX license identifiers.

language_structure.sh

Validates Joomla language directory structure and INI files.

changelog.sh

Validates CHANGELOG.md structure and version entries.

Fix Scripts (fix/)

These scripts automatically fix common issues detected by validation scripts.

tabs.sh

Replaces tab characters with spaces in YAML files.

Usage:

./scripts/fix/tabs.sh

paths.sh

Normalizes Windows-style path separators to forward slashes.

Usage:

./scripts/fix/paths.sh [directory]

versions.sh

Updates version numbers across repository files.

Usage:

./scripts/fix/versions.sh <VERSION>

Example:

./scripts/fix/versions.sh 3.5.0

Updates:

• Manifest XML <version> tag
• package.json version field
• Version references in README.md

Release Scripts (release/)

Scripts for release automation and version management.

update_changelog.sh

Inserts a new version entry in CHANGELOG.md.

Usage:

./scripts/release/update_changelog.sh <VERSION>

Example:

./scripts/release/update_changelog.sh 03.05.00

update_dates.sh

Normalizes release dates across manifests and CHANGELOG.

Usage:

./scripts/release/update_dates.sh <YYYY-MM-DD> <VERSION>

Example:

./scripts/release/update_dates.sh 2025-01-15 03.05.00

Run Scripts (run/)

Execution and testing scripts.

smoke_test.sh

Runs basic smoke tests to verify repository health:

• Repository structure validation
• Manifest validation
• Version alignment checks
• PHP syntax validation

Usage:

./scripts/run/smoke_test.sh

Example output:

INFO: Running smoke tests for Moko-Cassiopeia repository
INFO: Checking repository structure...
INFO: ✓ Repository structure valid
INFO: Checking Joomla manifest...
INFO: Found manifest: src/templates/templateDetails.xml
INFO: Extension: moko-cassiopeia (template) v03.05.00
INFO: ✓ Manifest validation passed
INFO: =========================================
INFO: Smoke tests completed successfully
INFO: =========================================

validate_all.sh

Runs all validation scripts and provides a comprehensive report:

• Executes all required validation checks
• Executes all optional validation checks
• Provides colored output with pass/fail indicators
• Returns summary with counts
• Supports verbose mode for detailed output

Usage:

./scripts/run/validate_all.sh        # Standard mode
./scripts/run/validate_all.sh -v     # Verbose mode (shows all output)

Example output:

=== Repository Validation Suite ===
INFO: Running all validation checks...

=== Required Checks ===
[SUCCESS] ✓ manifest
[SUCCESS] ✓ xml_wellformed

=== Optional Checks ===
[SUCCESS] ✓ no_secrets
[SUCCESS] ✓ php_syntax
WARN: ✗ tabs (warnings/issues found - run with -v for details)

=== Validation Summary ===
  Required checks passed: 2/2
  Optional checks passed: 2/8
[SUCCESS] SUCCESS: All required checks passed

Best Practices

Writing New Scripts

1. Use the library functions:

   #!/usr/bin/env bash
   set -euo pipefail
   
   SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
   . "${SCRIPT_DIR}/lib/common.sh"
   

2. Include proper headers:

   • Copyright notice
   • SPDX license identifier
   • FILE INFORMATION section with DEFGROUP, INGROUP, PATH, VERSION, BRIEF

3. Follow error handling conventions:

   [ -f "${FILE}" ] || die "File not found: ${FILE}"
   require_cmd python3
   

4. Use structured output:

   log_info "Starting process..."
   log_success "Process completed"
   

5. Make scripts executable:

   chmod +x scripts/new-script.sh
   

Testing Scripts Locally

Run all validation scripts:

./scripts/run/validate_all.sh

Run individual validation scripts:

./scripts/validate/manifest.sh
./scripts/validate/php_syntax.sh
./scripts/validate/tabs.sh

Run smoke tests:

./scripts/run/smoke_test.sh

CI Integration

Scripts are automatically executed in GitHub Actions workflows:

• .github/workflows/ci.yml - Continuous integration
• .github/workflows/repo_health.yml - Repository health checks

Version History

Version	Date	Description
01.00.00	2025-01-03	Initial scripts documentation created

Metadata

• Document: scripts/README.md
• Repository: https://github.com/mokoconsulting-tech/moko-cassiopeia
• Version: 01.00.00
• Status: Active