docopslab-dev 0.1.0

data/assets/config-packs/vale/config/scripts/ExplicitSectionIDs.tengo

@@ -0,0 +1,56 @@
+text := import("text")
+
+matches := []
+lines := text.split(scope, "\n")
+
+// byte starts (CRLF-safe)
+starts := []
+run := 0
+i := 0
+for i < len(lines) {
+    starts = append(starts, run)
+    run = run + len(lines[i]) + 1
+    i = i + 1
+}
+
+idRe     := `^\[\[[A-Za-z0-9_-]+\]\]$`
+h2plusRe := `^={2,}\s+.+$`
+commentRe := `^\s*//`
+condRe    := `^\s*(ifdef|ifndef|ifeval)::`
+
+j := 0
+for j < len(lines) {
+    line := lines[j]
+    
+    // Check if this is a section heading (level 2+)
+    if text.re_match(h2plusRe, line) {
+        // Walk backward from j-1 to find the ID, skipping comments/conditionals
+        hasID := false
+        k := j - 1
+        
+        for k >= 0 {
+            candidate := text.trim_space(lines[k])
+            
+            // Skip empty lines, comments, and conditionals
+            if candidate == "" || text.re_match(commentRe, candidate) || text.re_match(condRe, candidate) {
+                k = k - 1
+                continue
+            }
+            
+            // Check if this line is an ID
+            if text.re_match(idRe, candidate) {
+                hasID = true
+            }
+            
+            // Stop at first non-skippable line
+            break
+        }
+        
+        if !hasID {
+            begin := starts[j]
+            end   := begin + len(line)
+            matches = append(matches, {"begin": begin, "end": end})
+        }
+    }
+    j = j + 1
+}

data/assets/config-packs/vale/config/scripts/ExtraLineBeforeLevel1.tengo

@@ -0,0 +1,121 @@
+text := import("text")
+
+matches := []
+lines := text.split(scope, "\n")
+
+// byte starts (CRLF-safe)
+starts := []
+run := 0
+i := 0
+for i < len(lines) {
+    starts = append(starts, run)
+    run = run + len(lines[i]) + 1
+    i = i + 1
+}
+
+commentRe := `^\s*//`
+condRe    := `^\s*(ifdef|ifndef|ifeval)::`
+idRe      := `^\[\[[A-Za-z0-9_-]+\]\]$`
+h1Re      := `^==\s+.+$`
+
+j := 0
+for j < len(lines) {
+    line := lines[j]
+
+    // Check if this is a level-1 heading
+    if text.re_match(h1Re, line) {
+        // Step 1: Walk backward from heading to find ID (required)
+        k := j - 1
+        idLineNum := -1
+        
+        // Skip backwards over comments/conditionals between ID and heading
+        for k >= 0 {
+            candidate := text.trim_space(lines[k])
+            
+            // Skip comments and conditionals
+            if text.re_match(commentRe, candidate) || text.re_match(condRe, candidate) {
+                k = k - 1
+                continue
+            }
+            
+            // If blank, no ID found
+            if candidate == "" {
+                break
+            }
+            
+            // Check if this is the ID
+            if text.re_match(idRe, candidate) {
+                idLineNum = k
+            }
+            
+            // Stop at first non-comment/conditional line
+            break
+        }
+        
+        // If no ID was found, flag this heading
+        if idLineNum == -1 {
+            begin := starts[j]
+            end   := begin + len(line)
+            matches = append(matches, {"begin": begin, "end": end})
+            j = j + 1
+            continue
+        }
+        
+        // Step 2: Walk backward from ID to find start of section header block
+        // Section header includes: opening conditionals/comments that are adjacent to ID (no blanks between)
+        m := idLineNum - 1
+        sectionStart := idLineNum
+        
+        for m >= 0 {
+            candidate := text.trim_space(lines[m])
+            
+            // If blank, stop - section header block ends here
+            if candidate == "" {
+                break
+            }
+            
+            // If comment or conditional, it's part of section header block
+            if text.re_match(commentRe, candidate) || text.re_match(condRe, candidate) {
+                sectionStart = m
+                m = m - 1
+                continue
+            }
+            
+            // Hit other content, stop
+            break
+        }
+        
+        // Step 3: Count blank lines immediately before section header block start
+        n := sectionStart - 1
+        blanks := 0
+        
+        for n >= 0 {
+            candidate := text.trim_space(lines[n])
+            
+            // Count consecutive blank lines
+            if candidate == "" {
+                blanks = blanks + 1
+                n = n - 1
+                continue
+            }
+            
+            // Hit non-blank, stop counting
+            break
+        }
+        
+        // If we reached the start of file without hitting content, don't require blanks
+        if n < 0 {
+            j = j + 1
+            continue
+        }
+        
+        // Require exactly 2 blank lines before the section header block
+        if blanks != 2 {
+            begin := starts[j]
+            end   := begin + len(line)
+            matches = append(matches, {"begin": begin, "end": end})
+        }
+    }
+
+    j = j + 1
+}

data/assets/config-packs/vale/config/scripts/OneSentencePerLine.tengo

@@ -0,0 +1,53 @@
+text := import("text")
+
+matches := []
+
+lines := text.split(scope, "\n")
+
+starts := []
+run := 0
+i := 0
+for i < len(lines) {
+  line := lines[i]
+  starts = append(starts, run)
+  run = run + len(line) + 1
+  i = i + 1
+}
+
+// require an alnum/closer BEFORE .!? to avoid leading "." list markers
+boundary := `[A-Za-z0-9\)\]"'][.!?]['")\]]*[ \t]+[A-Z]`
+
+j := 0
+for j < len(lines) {
+  line := lines[j]
+
+  // skip attribute/table/heading lines
+  if text.re_match(`^[:|=]`, line) {
+    j = j + 1
+    continue
+  }
+
+  // skip numbered list items (e.g., "1. Something") unless prefaced by comment chars
+  // Allow: // 1. Something or # 1. Another thing
+  // Don't allow: 1. Something
+  if text.re_match(`^\d+\.\s+\w`, line) && !text.re_match(`^[/#]+\s*\d+\.\s+\w`, line) {
+    j = j + 1
+    continue
+  }
+
+  // skip ALL commented lines that start with number and period (like "# 1. Something")
+  if text.re_match(`^[/#]+\s*\d+\.\s`, line) {
+    j = j + 1
+    continue
+  }
+
+  if text.re_match(boundary, line) {
+    begin := starts[j]
+    end   := begin + len(line)
+    matches = append(matches, {"begin": begin, "end": end})
+  }
+
+  j = j + 1
+}
+
+// no explicit return

data/assets/config-packs/vale/project.ini

@@ -0,0 +1,5 @@
+# DocOps Lab Vale Configuration
+# Combined base and project configuration for consistent Vale linting
+
+MinAlertLevel = error
+StylesPath = .vendor/vale/styles

data/assets/hooks/pre-commit

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# DocOps Lab pre-commit hook template
+# Managed by docopslab-dev gem
+# Developer-friendly: warns about issues but doesn't block commits
+
+set -e
+
+echo "🪝 DocOps Lab pre-commit advisory checks..."
+
+# Get list of staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+if [[ -z "$STAGED_FILES" ]]; then
+  echo "ℹ️  No files staged for commit."
+  exit 0
+fi
+
+# Advisory config sync check (non-blocking)
+if [[ -f ".config/docopslab-dev.yml" ]] && command -v bundle &> /dev/null; then
+  echo "🔄 Checking config sync status..."
+  if bundle exec rake labdev:config:sync --dry-run &> /dev/null; then
+    echo "✅ Config sync up to date"
+  else
+    echo "💡 Config sync available. Run after commit: bundle exec rake labdev:config:sync"
+  fi
+fi
+
+# Quick syntax check on staged Ruby files (non-blocking)
+RUBY_FILES=$(echo "$STAGED_FILES" | grep -E '\.(rb|rake)$|^Rakefile$' || true)
+if [[ -n "$RUBY_FILES" ]]; then
+  echo "🔍 Quick syntax check on staged Ruby files..."
+  for file in $RUBY_FILES; do
+    if ! ruby -c "$file" &> /dev/null; then
+      echo "⚠️  Syntax error in $file - consider fixing before push"
+    fi
+  done
+fi
+
+# For Bash files, ensure proper shebang
+# Look for .sh files recursively but also search for files with 1. no extensions AND 2. a shebang on the first line that includes "bash" or "sh"
+BASH_FILES=$(echo "$STAGED_FILES" | grep -E '\.sh$|^([^./]+)$' | while read -r file; do
+  if head -n 1 "$file" | grep -qE '^#!.*\b(bash|sh)\b'; then
+    echo "$file"
+  fi
+done)
+if [[ -n "$BASH_FILES" ]]; then
+  for file in $BASH_FILES; do
+    if head -n 1 "$file" | grep -qv '^#!/usr/bin/env bash'; then
+      echo "❌ Incorrect shebang in $file. Please use '#!/usr/bin/env bash'."
+      exit 1
+    fi
+  done
+fi
+
+# Show helpful next steps
+echo ""
+echo "💡 After committing, consider running:"
+echo "   • bundle exec rake labdev:heal     # Auto-fix linting issues"
+echo "   • bundle exec rake labdev:assess  # Check environment"
+echo "   • bundle exec rake labdev:lint:all # Full quality check"
+echo ""
+echo "✅ Commit proceeding (full quality gate runs on push)"
+exit 0

data/assets/hooks/pre-push

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# DocOps Lab pre-push hook template
+# Managed by docopslab-dev gem
+# Runs comprehensive linting before pushing to prevent issues in CI
+
+set -e
+
+echo "🚀 DocOps Lab pre-push quality gate..."
+
+# Check if we have any commits to push
+LOCAL=$(git rev-parse @)
+REMOTE=$(git rev-parse '@{u}' 2>/dev/null || echo "")
+BASE=$(git merge-base @ '@{u}' 2>/dev/null || echo "")
+
+if [[ -z "$REMOTE" ]]; then
+  echo "ℹ️  No remote tracking branch found, skipping pre-push checks."
+  exit 0
+fi
+
+if [[ "$LOCAL" = "$REMOTE" ]]; then
+  echo "ℹ️  No new commits to push."
+  exit 0
+fi
+
+if git diff --cached --name-only | grep -q 'Gemfile'; then
+  if git diff --cached -U0 | grep -E '^\+.*gem [a-zA-Z0-9_-]+ .+ path:\s*['"'"'"].+['"'"'"]'; then
+    echo ""
+    echo "⚠️  Warning: Detected gems with local path: parameters in Gemfile changes."
+    echo "💡 Consider using published gems from RubyGems.org or Git hosting services instead."
+    echo ""
+  fi
+fi
+
+echo "📋 Checking commits from $BASE to $LOCAL..."
+
+# Run all linters on the codebase
+echo "🔍 Running comprehensive linting..."
+
+# Check config sync status first
+if [[ -f ".config/docopslab-dev.yml" ]]; then
+  echo "🔄 Verifying config sync..."
+  if command -v bundle &> /dev/null; then
+    if ! bundle exec rake labdev:config:sync --dry-run &> /dev/null; then
+      echo "❌ Config sync needed. Run: bundle exec rake labdev:config:sync"
+      exit 1
+    fi
+    echo "✅ Config sync verified"
+  fi
+fi
+
+# Run all linters
+if command -v bundle &> /dev/null; then
+  echo "🧹 Running all linters..."
+  if ! bundle exec rake labdev:lint:all; then
+    echo ""
+    echo "❌ Quality gate failed!"
+    echo "💡 Suggested workflow:"
+    echo "   1. Run: bundle exec rake labdev:heal"
+    echo "   2. Review changes with: git diff"
+    echo "   3. Commit auto-fixes: git commit -am 'Auto-fix linting issues'"
+    echo "   4. Fix remaining issues manually"
+    echo "   5. Try pushing again"
+    echo ""
+    echo "🚫 Or bypass with: git push --no-verify"
+    exit 1
+  fi
+else
+  echo "⚠️  Bundle not available, skipping linting checks"
+fi
+
+echo "✅ Pre-push quality gate passed"
+exit 0

data/assets/scripts/adoc_section_ids.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+def generate_id_from_heading heading
+  heading.gsub(/\b(a|an|the|and|or|but|for|nor|on|at|to|from|by|in|of|is|are|was|were|be|being|been)\b/i, '')
+         .gsub(/[^\w\s-]/, '').strip
+         .squeeze(' ')
+         .gsub(' ', '-').downcase
+  heading.strip.downcase.gsub(/[^a-z0-9]+/, '-').gsub(/^-|-$/, '')
+end
+
+def process_adoc_file file_path
+  lines = File.readlines(file_path)
+  updated_lines = []
+  i = 0
+
+  while i < lines.size
+    line = lines[i]
+    if line =~ /^(={2,})\s([A-Z].*)$/ # Match AsciiDoc headings (2+ = chars)
+      Regexp.last_match(1)
+      heading_text = Regexp.last_match(2)
+
+      # Check if previous line is an explicit ID
+      if i.zero? || lines[i - 1] !~ /^\[\[.*\]\]$/
+        generated_id = generate_id_from_heading(heading_text)
+        updated_lines << "[[#{generated_id}]]\n"
+      end
+    end
+    updated_lines << line
+    i += 1
+  end
+
+  File.write(file_path, updated_lines.join)
+  puts "Processed file: #{file_path}"
+end
+
+# We need an alternative to optparse, hopefully using no dependencies
+
+if ARGV.empty?
+  puts 'Usage: ruby adoc_section_ids.rb <asciidoc_file1> [<asciidoc_file2> ...]'
+  exit 1
+end
+
+ARGV.each do |file_path|
+  unless File.exist?(file_path)
+    puts "File not found: #{file_path}"
+    next
+  end
+
+  process_adoc_file(file_path)
+end

data/assets/scripts/build-common.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+# Common build functions for DocOps Lab Ruby gem projects
+# This library provides reusable functions for building gems and Docker images
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Project configuration - these should be set by the calling script
+PROJECT_NAME="${PROJECT_NAME:-$(basename "$(pwd)")}"
+DOCKER_ORG="${DOCKER_ORG:-docopslab}"
+GEMSPEC_FILE="${GEMSPEC_FILE:-${PROJECT_NAME}.gemspec}"
+CLI_EXECUTABLE="${CLI_EXECUTABLE:-exe/${PROJECT_NAME}}"
+EXAMPLE_FILE="${EXAMPLE_FILE:-examples/minimal-example.yml}"
+TEST_SPEC_PATH="${TEST_SPEC_PATH:-specs/tests/rspec/}"
+
+# Common validation functions
+check_project_root() {
+    if [ ! -f "$GEMSPEC_FILE" ]; then
+        echo -e "${RED}❌ Error: $GEMSPEC_FILE not found. Run this script from the project root.${NC}"
+        exit 1
+    fi
+}
+
+check_docker_available() {
+    if ! command -v docker &> /dev/null; then
+        echo -e "${RED}❌ Error: Docker is not installed or not in PATH${NC}"
+        exit 1
+    fi
+}
+
+check_git_clean() {
+    if [ -n "$(git status --porcelain)" ]; then
+        echo -e "${RED}❌ Error: Working directory is not clean. Commit or stash changes first.${NC}"
+        git status --short
+        exit 1
+    fi
+}
+
+check_main_branch() {
+    current_branch=$(git branch --show-current)
+    if [ "$current_branch" != "main" ]; then
+        echo -e "${YELLOW}⚠️  Warning: Not on main branch (currently on: $current_branch)${NC}"
+        read -p "Continue anyway? (y/N): " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo "Aborted."
+            exit 1
+        fi
+    fi
+}
+
+check_bundle_installed() {
+    if [ ! -f "Gemfile" ]; then
+        echo -e "${YELLOW}⚠️  Warning: No Gemfile found. Some operations may require dependencies.${NC}"
+        return
+    fi
+    
+    if ! bundle check > /dev/null 2>&1; then
+        echo -e "${YELLOW}📦 Installing gem dependencies...${NC}"
+        bundle install
+    fi
+}
+
+# Get current version from README.adoc by parsing directly
+get_current_version() {
+    grep '^:this_prod_vrsn:' README.adoc | sed 's/^:this_prod_vrsn:[[:space:]]*//' | tr -d '\r'
+}
+
+# Get next version from README.adoc by parsing directly
+get_next_version() {
+    grep '^:next_prod_vrsn:' README.adoc | sed 's/^:next_prod_vrsn:[[:space:]]*//' | tr -d '\r'
+}
+
+# Docker build and test functions
+build_docker_image() {
+    local version=$1
+    local docker_args="${2:-}"
+    
+    echo -e "${YELLOW}🐳 Building Docker image...${NC}"
+    # shellcheck disable=SC2086
+    docker build ${docker_args} -t "${DOCKER_ORG}/${PROJECT_NAME}:${version}" .
+    docker tag "${DOCKER_ORG}/${PROJECT_NAME}:${version}" "${DOCKER_ORG}/${PROJECT_NAME}:latest"
+}
+
+test_docker_image() {
+    local version=$1
+    local image_name="${DOCKER_ORG}/${PROJECT_NAME}:${version}"
+    
+    echo -e "${YELLOW}🧪 Testing Docker image...${NC}"
+    docker run --rm -v "$(pwd):/workdir" "${image_name}" --version
+    
+    if [ -f "$EXAMPLE_FILE" ]; then
+        docker run --rm -v "$(pwd):/workdir" "${image_name}" "${EXAMPLE_FILE}" --dry
+    fi
+}
+
+# Test functions
+run_rspec_tests() {
+    if [ -d "$TEST_SPEC_PATH" ]; then
+        echo -e "${YELLOW}🧪 Running RSpec tests...${NC}"
+        bundle exec rspec "$TEST_SPEC_PATH" --format documentation
+    else
+        echo -e "${YELLOW}⚠️  No RSpec tests found at $TEST_SPEC_PATH${NC}"
+    fi
+}
+
+test_cli_functionality() {
+    if [ -x "$CLI_EXECUTABLE" ]; then
+        echo -e "${YELLOW}🧪 Testing CLI functionality...${NC}"
+        $CLI_EXECUTABLE --version
+        
+        if [ -f "$EXAMPLE_FILE" ]; then
+            $CLI_EXECUTABLE "$EXAMPLE_FILE" --dry
+        fi
+    else
+        echo -e "${YELLOW}⚠️  CLI executable not found at $CLI_EXECUTABLE${NC}"
+    fi
+}
+
+# Gem build functions
+build_gem() {
+    echo -e "${YELLOW}💎 Building gem...${NC}"
+    bundle exec rake build
+}
+
+test_built_gem() {
+    local current_version
+    current_version=$(get_current_version)
+    local gem_file="pkg/${PROJECT_NAME}-${current_version}.gem"
+    
+    if [ ! -f "$gem_file" ]; then
+        echo -e "${RED}❌ Error: Expected gem file not found: $gem_file${NC}"
+        exit 1
+    fi
+    
+    echo -e "${GREEN}✅ Built gem: $gem_file${NC}"
+    echo "$gem_file"
+}
+
+# Success message functions
+show_build_success() {
+    local version=$1
+    local gem_file=$2
+    
+    echo
+    echo -e "${GREEN}🎉 Build completed successfully!${NC}"
+    echo "=================================="
+    echo -e "${GREEN}📋 Version: $version${NC}"
+    echo -e "${GREEN}💎 Gem: $gem_file${NC}"
+    echo -e "${GREEN}🐳 Docker: ${DOCKER_ORG}/${PROJECT_NAME}:$version${NC}"
+    echo
+}
+
+show_docker_success() {
+    local version=$1
+    
+    echo
+    echo -e "${GREEN}🎉 Docker build completed successfully!${NC}"
+    echo "=================================="
+    echo -e "${GREEN}📋 Version: $version${NC}"
+    echo -e "${GREEN}🐳 Images built:${NC}"
+    echo "   ${DOCKER_ORG}/${PROJECT_NAME}:$version"
+    echo "   ${DOCKER_ORG}/${PROJECT_NAME}:latest"
+}
+
+# Version bump functions
+bump_version() {
+    local current_version
+    local next_version
+    current_version=$(get_current_version)
+    next_version=$(get_next_version)
+    
+    if [ "$current_version" = "$next_version" ]; then
+        echo -e "${RED}❌ Error: Current and next versions are the same: $current_version${NC}"
+        echo "Update :next_prod_vrsn: in README.adoc first"
+        exit 1
+    fi
+    
+    echo -e "${YELLOW}📝 Bumping version from $current_version to $next_version...${NC}"
+    
+    # Update the current version to match next version
+    sed -i "s/^:this_prod_vrsn: $current_version/:this_prod_vrsn: $next_version/" README.adoc
+    
+    # Commit the version bump
+    git add README.adoc
+    git commit -m "Release v$next_version"
+    git tag "v$next_version"
+    
+    echo -e "${GREEN}✅ Version bumped and tagged: v$next_version${NC}"
+}

data/assets/scripts/build-docker.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Generic Docker build script for DocOps Lab projects
+# Usage: Set PROJECT_NAME and DOCKER_ORG, then run this script
+
+set -e
+
+# Load common build functions from centrally managed location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Try to find build-common.sh in various locations
+if [ -f "$SCRIPT_DIR/build-common.sh" ]; then
+  # shellcheck source=build-common.sh
+  source "$SCRIPT_DIR/build-common.sh"
+elif [ -f "$SCRIPT_DIR/lib/build-common.sh" ]; then
+  # shellcheck source=build-common.sh
+  source "$SCRIPT_DIR/lib/build-common.sh"
+elif [ -f "scripts/.vendor/docopslab/build-common.sh" ]; then
+    # shellcheck source=build-common.sh
+  source "scripts/.vendor/docopslab/build-common.sh"
+else
+  echo "❌ Error: build-common.sh not found. Run 'rake labdev:config:sync' to get centrally managed scripts."
+  exit 1
+fi
+
+# Project configuration - override these in your calling script or environment
+PROJECT_NAME="${PROJECT_NAME:-$(basename "$(pwd)")}"
+DOCKER_ORG="${DOCKER_ORG:-docopslab}"
+
+echo -e "${GREEN}🐳 ${PROJECT_NAME} Docker Build Script${NC}"
+echo "=================================="
+
+# Validation
+check_project_root
+check_docker_available
+
+# Get current version
+current_version=$(get_current_version)
+echo -e "${GREEN}📋 Current version: $current_version${NC}"
+
+# Check if gem exists in pkg/, if not build it
+gem_file="pkg/${PROJECT_NAME}-$current_version.gem"
+if [ ! -f "$gem_file" ]; then
+    echo -e "${YELLOW}🔨 Gem not found in pkg/. Building gem first...${NC}"
+    check_bundle_installed
+    build_gem
+    echo -e "${GREEN}✅ Gem built: $gem_file${NC}"
+else
+    echo -e "${GREEN}📋 Using existing gem: $gem_file${NC}"
+fi
+
+# Build and test Docker image
+build_docker_image "$current_version"
+test_docker_image "$current_version"
+
+# Show success message
+show_docker_success "$current_version"
+
+echo
+echo "Test the image with:"
+echo "  docker run --rm -v \$(pwd):/workdir ${DOCKER_ORG}/${PROJECT_NAME}:$current_version --version"
+
+if [ -f "$EXAMPLE_FILE" ]; then
+    echo "  docker run --rm -v \$(pwd):/workdir ${DOCKER_ORG}/${PROJECT_NAME}:$current_version $EXAMPLE_FILE --dry"
+fi