Add enterprise-grade standards to scripts

- Add copyright headers to all validation scripts - Add usage/help functions to user-facing scripts - Enhance common.sh with dependency checking and timestamps - Add ENTERPRISE.md with comprehensive standards documentation - Update scripts/README.md with enterprise features section - Improve error messages and exit code handling Co-authored-by: jmiller-moko <230051081+jmiller-moko@users.noreply.github.com>
2026-01-03 23:08:55 +00:00
parent 0f15207d49
commit f2b8bc9003
16 changed files with 1063 additions and 6 deletions
--- a/scripts/ENTERPRISE.md
+++ b/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