Implement core script improvements

- Add joomla_manifest.sh library with manifest parsing functions
- Add smoke_test.sh for repository validation
- Add versions.sh for version management
- Add JSON utilities to common.sh
- Fix logging.sh with proper enhanced logging functions
- Make all scripts executable

Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>

scripts/fix/versions.sh

@@ -0,0 +1,150 @@
+#!/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.Fix
+# INGROUP: Version.Management
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/fix/versions.sh
+# VERSION: 01.00.00
+# BRIEF: Update version numbers across repository files
+# NOTE: Updates manifest, package.json, and other version references
+# ============================================================================
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+. "${SCRIPT_DIR}/lib/common.sh"
+
+# ----------------------------------------------------------------------------
+# Usage and validation
+# ----------------------------------------------------------------------------
+
+usage() {
+cat <<-USAGE
+Usage: $0 <VERSION>
+
+Update version numbers across repository files.
+
+Arguments:
+  VERSION    Semantic version in format X.Y.Z (e.g., 3.5.0)
+
+Examples:
+  $0 3.5.0
+  $0 1.2.3
+USAGE
+exit 1
+}
+
+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
+}
+
+# ----------------------------------------------------------------------------
+# Main
+# ----------------------------------------------------------------------------
+
+[ $# -eq 1 ] || usage
+
+VERSION="$1"
+validate_version "${VERSION}"
+
+log_info "Updating version to: ${VERSION}"
+
+# Source Joomla manifest utilities
+. "${SCRIPT_DIR}/lib/joomla_manifest.sh"
+
+# Find and update manifest
+MANIFEST="$(find_manifest src)"
+log_info "Updating manifest: ${MANIFEST}"
+
+# Cross-platform sed helper
+sed_inplace() {
+local expr="$1"
+local file="$2"
+
+if sed --version >/dev/null 2>&1; then
+sed -i -E "${expr}" "${file}"
+else
+sed -i '' -E "${expr}" "${file}"
+fi
+}
+
+# Update version in manifest XML
+if grep -q '<version>' "${MANIFEST}"; then
+sed_inplace "s|<version>[^<]*</version>|<version>${VERSION}</version>|g" "${MANIFEST}"
+log_info "✓ Updated manifest version"
+else
+log_warn "No <version> tag found in manifest"
+fi
+
+# Update package.json if it exists
+if [ -f "package.json" ]; then
+if command -v python3 >/dev/null 2>&1; then
+python3 - <<PY "${VERSION}"
+import json
+import sys
+
+version = sys.argv[1]
+
+try:
+with open('package.json', 'r') as f:
+data = json.load(f)
+
+data['version'] = version
+
+with open('package.json', 'w') as f:
+json.dump(data, f, indent=2)
+f.write('\n')
+
+print(f"✓ Updated package.json to version {version}")
+except Exception as e:
+print(f"WARN: Failed to update package.json: {e}")
+sys.exit(0)
+PY
+fi
+fi
+
+# Update README.md version references
+if [ -f "README.md" ]; then
+# Look for version references in format VERSION: XX.XX.XX
+if grep -q 'VERSION: [0-9]' README.md; then
+# Convert to zero-padded format if needed
+PADDED_VERSION="$(printf '%s' "${VERSION}" | awk -F. '{printf "%02d.%02d.%02d", $1, $2, $3}')"
+sed_inplace "s|VERSION: [0-9]{2}\.[0-9]{2}\.[0-9]{2}|VERSION: ${PADDED_VERSION}|g" README.md
+log_info "✓ Updated README.md version references"
+fi
+fi
+
+log_info "========================================="
+log_info "Version update completed: ${VERSION}"
+log_info "Files updated:"
+log_info "  - ${MANIFEST}"
+[ -f "package.json" ] && log_info "  - package.json"
+[ -f "README.md" ] && log_info "  - README.md"
+log_info "========================================="

scripts/lib/common.sh

@@ -102,6 +102,33 @@ normalize_path() {
 	printf '%s\n' "$1" | sed 's|\\|/|g'
 }
 
+# ----------------------------------------------------------------------------
+# JSON utilities
+# ----------------------------------------------------------------------------
+
+json_escape() {
+	require_cmd python3
+	python3 -c 'import json,sys; print(json.dumps(sys.argv[1]))' "$1"
+}
+
+json_output() {
+	local status="$1"
+	shift
+	require_cmd python3
+	python3 - <<PY "$status" "$@"
+import json
+import sys
+status = sys.argv[1]
+pairs = sys.argv[2:]
+data = {"status": status}
+for pair in pairs:
+	if "=" in pair:
+		k, v = pair.split("=", 1)
+		data[k] = v
+print(json.dumps(data, ensure_ascii=False))
+PY
+}
+
 # ----------------------------------------------------------------------------
 # Guardrails
 # ----------------------------------------------------------------------------

scripts/lib/joomla_manifest.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env sh
+
+# ============================================================================
+# 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.Library
+# INGROUP: Joomla.Manifest
+# REPO: https://github.com/mokoconsulting-tech
+# PATH: /scripts/lib/joomla_manifest.sh
+# VERSION: 01.00.00
+# BRIEF: Joomla manifest parsing and validation utilities
+# NOTE: Provides reusable functions for working with Joomla extension manifests
+# ============================================================================
+
+set -eu
+
+# Resolve script directory properly - works when sourced
+if [ -n "${SCRIPT_DIR:-}" ]; then
+	# Already set by caller
+	SCRIPT_LIB_DIR="${SCRIPT_DIR}/lib"
+else
+	# Determine from this file's location
+	SCRIPT_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+fi
+
+# Shared utilities
+. "${SCRIPT_LIB_DIR}/common.sh"
+
+# ----------------------------------------------------------------------------
+# Manifest discovery
+# ----------------------------------------------------------------------------
+
+# Find the primary Joomla manifest in the given directory
+# Usage: find_manifest <src_dir>
+# Returns: path to manifest file or exits with error
+find_manifest() {
+local src_dir="${1:-src}"
+
+[ -d "${src_dir}" ] || die "Source directory missing: ${src_dir}"
+
+# Candidate discovery policy: prefer explicit known names
+local candidates=""
+
+# Template
+if [ -f "${src_dir}/templateDetails.xml" ]; then
+candidates="${src_dir}/templateDetails.xml"
+fi
+
+# Package
+if [ -z "${candidates}" ]; then
+candidates="$(find "${src_dir}" -maxdepth 4 -type f -name 'pkg_*.xml' 2>/dev/null | head -1 || true)"
+fi
+
+# Component
+if [ -z "${candidates}" ]; then
+candidates="$(find "${src_dir}" -maxdepth 4 -type f -name 'com_*.xml' 2>/dev/null | head -1 || true)"
+fi
+
+# Module
+if [ -z "${candidates}" ]; then
+candidates="$(find "${src_dir}" -maxdepth 4 -type f -name 'mod_*.xml' 2>/dev/null | head -1 || true)"
+fi
+
+# Plugin
+if [ -z "${candidates}" ]; then
+candidates="$(find "${src_dir}" -maxdepth 6 -type f -name 'plg_*.xml' 2>/dev/null | head -1 || true)"
+fi
+
+# Fallback: any XML containing <extension ...>
+if [ -z "${candidates}" ]; then
+candidates="$(grep -Rsl --include='*.xml' '<extension' "${src_dir}" 2>/dev/null | head -1 || true)"
+fi
+
+[ -n "${candidates}" ] || die "No Joomla manifest XML found under ${src_dir}"
+[ -s "${candidates}" ] || die "Manifest is empty: ${candidates}"
+
+printf '%s\n' "${candidates}"
+}
+
+# ----------------------------------------------------------------------------
+# Manifest parsing
+# ----------------------------------------------------------------------------
+
+# Extract version from manifest XML
+# Usage: get_manifest_version <manifest_path>
+# Returns: version string or exits with error
+get_manifest_version() {
+	local manifest="$1"
+	
+	[ -f "${manifest}" ] || die "Manifest not found: ${manifest}"
+	
+	require_cmd python3
+	
+	python3 - "${manifest}" <<'PY'
+import sys
+import xml.etree.ElementTree as ET
+
+manifest_path = sys.argv[1]
+
+try:
+  tree = ET.parse(manifest_path)
+  root = tree.getroot()
+  version_el = root.find("version")
+  if version_el is not None and version_el.text:
+    print(version_el.text.strip())
+    sys.exit(0)
+except Exception:
+  pass
+
+sys.exit(1)
+PY
+}
+
+# Extract extension name from manifest XML
+# Usage: get_manifest_name <manifest_path>
+# Returns: name string or exits with error
+get_manifest_name() {
+	local manifest="$1"
+	
+	[ -f "${manifest}" ] || die "Manifest not found: ${manifest}"
+	
+	require_cmd python3
+	
+	python3 - "${manifest}" <<'PY'
+import sys
+import xml.etree.ElementTree as ET
+
+manifest_path = sys.argv[1]
+
+try:
+  tree = ET.parse(manifest_path)
+  root = tree.getroot()
+  name_el = root.find("name")
+  if name_el is not None and name_el.text:
+    print(name_el.text.strip())
+    sys.exit(0)
+except Exception:
+  pass
+
+sys.exit(1)
+PY
+}
+
+# Extract extension type from manifest XML
+# Usage: get_manifest_type <manifest_path>
+# Returns: type string (template, component, module, plugin, etc.) or exits with error
+get_manifest_type() {
+	local manifest="$1"
+	
+	[ -f "${manifest}" ] || die "Manifest not found: ${manifest}"
+	
+	require_cmd python3
+	
+	python3 - "${manifest}" <<'PY'
+import sys
+import xml.etree.ElementTree as ET
+
+manifest_path = sys.argv[1]
+
+try:
+  tree = ET.parse(manifest_path)
+  root = tree.getroot()
+  ext_type = root.attrib.get("type", "").strip().lower()
+  if ext_type:
+    print(ext_type)
+    sys.exit(0)
+except Exception:
+  pass
+
+sys.exit(1)
+PY
+}

scripts/lib/logging.sh

@@ -25,96 +25,88 @@
 # FILE INFORMATION
 # ============================================================================
 # DEFGROUP: Script.Library
-# INGROUP: RepoHealth
+# INGROUP: Logging
 # REPO: https://github.com/mokoconsulting-tech
-# PATH: /scripts/lib/find_files.sh
+# PATH: /scripts/lib/logging.sh
 # VERSION: 01.00.00
-# BRIEF: Find files by glob patterns with standard ignore rules for CI checks
-# NOTE:
+# BRIEF: Enhanced logging utilities with structured output support
+# NOTE: Provides colored output, log levels, and structured logging
 # ============================================================================
 
 set -eu
 
+# Resolve script directory properly
+SCRIPT_LIB_DIR="$(cd "$(dirname "$0")" && pwd)"
+
 # Shared utilities
-. "$(dirname "$0")/common.sh"
+. "${SCRIPT_LIB_DIR}/common.sh"
 
 # ----------------------------------------------------------------------------
-# Purpose:
-# - Provide a consistent, reusable file discovery primitive for repo scripts.
-# - Support multiple glob patterns.
-# - Apply standard ignore rules to reduce noise (vendor, node_modules, .git).
-# - Output one path per line, relative to repo root.
-#
-# Usage:
-#   ./scripts/lib/find_files.sh <glob> [<glob> ...]
-#
-# Examples:
-#   ./scripts/lib/find_files.sh "*.yml" "*.yaml"
-#   ./scripts/lib/find_files.sh "src/**/*.php" "tests/**/*.php"
+# Color codes (if terminal supports it)
 # ----------------------------------------------------------------------------
 
-ROOT="$(script_root)"
-
-if [ "${1:-}" = "" ]; then
-	die "Usage: $0 <glob> [<glob> ...]"
-fi
-
-require_cmd find
-require_cmd sed
-
-# Standard excludes (pragmatic defaults for CI)
-# Note: Keep these broad to avoid scanning generated or third-party content.
-EXCLUDES='
-	-path "*/.git/*" -o
-	-path "*/.github/*/node_modules/*" -o
-	-path "*/node_modules/*" -o
-	-path "*/vendor/*" -o
-	-path "*/dist/*" -o
-	-path "*/build/*" -o
-	-path "*/cache/*" -o
-	-path "*/tmp/*" -o
-	-path "*/.tmp/*" -o
-	-path "*/.cache/*"
-'
-
-# Convert a glob (bash-like) to a find -path pattern.
-# - Supports ** for "any directories" by translating to *
-# - Ensures leading */ so patterns apply anywhere under repo root
-glob_to_find_path() {
-	g="$1"
-
-	# normalize path separators for WSL/CI compatibility
-	g="$(normalize_path "$g")"
-
-	# translate ** to * (find -path uses shell glob semantics)
-	g="$(printf '%s' "$g" | sed 's|\*\*|*|g')"
-
-	case "$g" in
-		/*) printf '%s\n' "$g" ;;
-		*)  printf '%s\n' "*/$g" ;;
-	esac
+# Check if we're in a terminal and colors are supported
+use_colors() {
+	[ -t 1 ] && [ "${CI:-false}" != "true" ]
 }
 
-# Build a single find invocation that ORs all patterns.
-# Shell portability note: avoid arrays; build an expression string.
-PAT_EXPR=""
-for GLOB in "$@"; do
-	P="$(glob_to_find_path "$GLOB")"
-	if [ -z "$PAT_EXPR" ]; then
-		PAT_EXPR="-path \"$P\""
-	else
-		PAT_EXPR="$PAT_EXPR -o -path \"$P\""
+if use_colors; then
+	COLOR_RESET='\033[0m'
+	COLOR_RED='\033[0;31m'
+	COLOR_YELLOW='\033[0;33m'
+	COLOR_GREEN='\033[0;32m'
+	COLOR_BLUE='\033[0;34m'
+	COLOR_CYAN='\033[0;36m'
+else
+	COLOR_RESET=''
+	COLOR_RED=''
+	COLOR_YELLOW=''
+	COLOR_GREEN=''
+	COLOR_BLUE=''
+	COLOR_CYAN=''
+fi
+
+# ----------------------------------------------------------------------------
+# Enhanced logging functions
+# ----------------------------------------------------------------------------
+
+log_debug() {
+	if [ "${DEBUG:-false}" = "true" ]; then
+		printf '%b[DEBUG]%b %s\n' "${COLOR_CYAN}" "${COLOR_RESET}" "$*"
 	fi
-done
+}
 
-# Execute find and emit relative paths.
-# - Use eval to apply the constructed predicate string safely as a single expression.
-# - We scope to files only.
-# - We prune excluded directories.
-cd "$ROOT"
+log_success() {
+	printf '%b[SUCCESS]%b %s\n' "${COLOR_GREEN}" "${COLOR_RESET}" "$*"
+}
+
+log_step() {
+	printf '%b[STEP]%b %s\n' "${COLOR_BLUE}" "${COLOR_RESET}" "$*"
+}
+
+# ----------------------------------------------------------------------------
+# Structured logging
+# ----------------------------------------------------------------------------
+
+# Log a key-value pair
+log_kv() {
+	local key="$1"
+	local value="$2"
+	printf '  %b%s:%b %s\n' "${COLOR_BLUE}" "${key}" "${COLOR_RESET}" "${value}"
+}
+
+# Log a list item
+log_item() {
+	printf '  %b•%b %s\n' "${COLOR_GREEN}" "${COLOR_RESET}" "$*"
+}
+
+# Log a separator line
+log_separator() {
+	printf '%s\n' "========================================="
+}
+
+# Log a section header
+log_section() {
+	printf '\n%b=== %s ===%b\n' "${COLOR_BLUE}" "$*" "${COLOR_RESET}"
+}
 
-# shellcheck disable=SC2086
-eval "find . \\( $EXCLUDES \\) -prune -o -type f \\( $PAT_EXPR \\) -print" \
-	| sed 's|^\./||' \
-	| sed '/^$/d' \
-	| sort -u

scripts/run/smoke_test.sh

@@ -0,0 +1,146 @@
+#!/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.Test
+# INGROUP: Repository.Validation
+# REPO: https://github.com/mokoconsulting-tech/moko-cassiopeia
+# PATH: /scripts/run/smoke_test.sh
+# VERSION: 01.00.00
+# BRIEF: Basic smoke tests to verify repository structure and manifest validity
+# NOTE: Quick validation checks for essential repository components
+# ============================================================================
+
+set -euo pipefail
+
+# Source common utilities
+SCRIPT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+. "${SCRIPT_DIR}/lib/common.sh"
+
+log_info "Running smoke tests for Moko-Cassiopeia repository"
+
+# ----------------------------------------------------------------------------
+# Test: Repository structure
+# ----------------------------------------------------------------------------
+
+log_info "Checking repository structure..."
+
+assert_dir_exists "src"
+assert_file_exists "README.md"
+assert_file_exists "CHANGELOG.md"
+assert_file_exists "LICENSE"
+assert_file_exists "CONTRIBUTING.md"
+
+log_info "✓ Repository structure valid"
+
+# ----------------------------------------------------------------------------
+# Test: Manifest validation
+# ----------------------------------------------------------------------------
+
+log_info "Checking Joomla manifest..."
+
+. "${SCRIPT_DIR}/lib/joomla_manifest.sh"
+
+MANIFEST="$(find_manifest src)"
+log_info "Found manifest: ${MANIFEST}"
+
+VERSION="$(get_manifest_version "${MANIFEST}")"
+NAME="$(get_manifest_name "${MANIFEST}")"
+TYPE="$(get_manifest_type "${MANIFEST}")"
+
+log_info "Extension: ${NAME} (${TYPE}) v${VERSION}"
+
+# Verify manifest is well-formed XML
+require_cmd python3
+python3 - "${MANIFEST}" <<'PY'
+import sys
+import xml.etree.ElementTree as ET
+
+manifest_path = sys.argv[1]
+
+try:
+  tree = ET.parse(manifest_path)
+  root = tree.getroot()
+  if root.tag != "extension":
+    print(f"ERROR: Root element must be <extension>, got <{root.tag}>")
+    sys.exit(1)
+  print("✓ Manifest XML is well-formed")
+except Exception as e:
+  print(f"ERROR: Failed to parse manifest: {e}")
+  sys.exit(1)
+PY
+
+log_info "✓ Manifest validation passed"
+
+# ----------------------------------------------------------------------------
+# Test: Version alignment
+# ----------------------------------------------------------------------------
+
+log_info "Checking version alignment..."
+
+if [ ! -f "CHANGELOG.md" ]; then
+log_warn "CHANGELOG.md not found, skipping version alignment check"
+else
+if grep -q "## \[${VERSION}\]" CHANGELOG.md; then
+log_info "✓ Version ${VERSION} found in CHANGELOG.md"
+else
+log_warn "Version ${VERSION} not found in CHANGELOG.md"
+fi
+fi
+
+# ----------------------------------------------------------------------------
+# Test: Critical files syntax
+# ----------------------------------------------------------------------------
+
+log_info "Checking PHP syntax..."
+
+if command -v php >/dev/null 2>&1; then
+php_errors=0
+while IFS= read -r -d '' f; do
+if ! php -l "$f" >/dev/null 2>&1; then
+log_error "PHP syntax error in: $f"
+php_errors=$((php_errors + 1))
+fi
+done < <(find src -type f -name '*.php' -print0 2>/dev/null)
+
+if [ "${php_errors}" -eq 0 ]; then
+log_info "✓ PHP syntax validation passed"
+else
+die "Found ${php_errors} PHP syntax errors"
+fi
+else
+log_warn "PHP not available, skipping PHP syntax check"
+fi
+
+# ----------------------------------------------------------------------------
+# Summary
+# ----------------------------------------------------------------------------
+
+log_info "========================================="
+log_info "Smoke tests completed successfully"
+log_info "Extension: ${NAME}"
+log_info "Version: ${VERSION}"
+log_info "Type: ${TYPE}"
+log_info "========================================="