docopslab-dev 0.1.0 → 0.3.0

data/docopslab-dev.gemspec

@@ -20,12 +20,10 @@ Gem::Specification.new do |spec|
   spec.metadata['changelog_uri'] = 'https://github.com/DocOps/lab/blob/main/gems/docopslab-dev/README.adoc'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
-  spec.files = Dir.glob('{lib,config-packs,hooks,docs,assets}/**/*') +
+  spec.files = Dir.glob('lib/**/*') +
                %w[README.adoc LICENSE docopslab-dev.gemspec] +
                Dir.glob('specs/data/*')
 
-  spec.bindir = 'exe'
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
   # Core runtime dependencies
@@ -34,6 +32,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'yaml', '~> 0.2'
 
   # Code quality and linting
+  spec.add_dependency 'asciisourcerer', '~> 0.2'
   spec.add_dependency 'debride',        '~> 1.13'
   spec.add_dependency 'fasterer',       '~> 0.11'
   spec.add_dependency 'flog',           '~> 4.8'
@@ -48,7 +47,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'bundler-audit',  '~> 0.9'
 
   # Testing and coverage
-  spec.add_dependency 'html-proofer',   '~> 5.0'
+  spec.add_dependency 'html-proofer',   '~> 5.2'
   spec.add_dependency 'inch',           '~> 0.8'
   spec.add_dependency 'simplecov',      '~> 0.22'
 

data/lib/docopslab/dev/cast_ops.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'sourcerer/sync'
+
+module DocOpsLab
+  module Dev
+    # Sync/Cast operations: synchronize canonical blocks from prime templates
+    # into project-local target files using Sourcerer::Sync.
+    #
+    # Prime templates define canonical (universal-prefixed) blocks.
+    # Target files receive those blocks on each sync, preserving all local content.
+    # On first-time init the whole prime is rendered and written as the new target.
+    #
+    # Configuration is driven by <tt>templates:</tt> in the project manifest.
+    # The list of template-to-target procedures lives under <tt>templates.manifest</tt>.
+    module CastOps
+      class << self
+        # Sync canonical blocks from prime templates into all configured target files.
+        #
+        # @param context [DocOpsLab::Dev] caller context (for manifest access)
+        # @param target_filter [String, nil] restrict to entries whose target matches
+        # @param dry_run [Boolean] compute diff but do not write
+        # @return [Hash{String => Sourcerer::Sync::Cast::CastResult}]
+        def sync_cast_targets context, target_filter: nil, dry_run: false
+          castings, global_data = load_castings(context, target_filter)
+          return {} unless castings
+
+          label = dry_run ? '🔍 Dry-run: diffing cast targets...' : '🔄 Syncing cast targets...'
+          puts label
+
+          results = {}
+          castings.each do |entry|
+            prime_path = resolve_prime(entry)
+            next unless prime_path
+
+            target_path = entry['target']
+
+            unless File.exist?(target_path)
+              puts "  ⚠️  Target not found: #{target_path} (run labdev:init:templates to bootstrap)"
+              next
+            end
+
+            data             = build_data(global_data, entry)
+            canonical_prefix = entry.fetch('canonical_prefix', 'universal-')
+
+            result = Sourcerer::Sync.sync(
+              prime_path,
+              target_path,
+              data: data,
+              canonical_prefix: canonical_prefix,
+              dry_run: dry_run)
+
+            results[target_path] = result
+            report_result(result, dry_run: dry_run)
+          end
+
+          puts "✅ Synced #{results.count { |_, r| r.applied_changes.any? }} cast target(s)" unless dry_run
+          results
+        end
+
+        # Bootstrap new target files from prime templates.
+        # Skips targets that already exist (use sync to update those).
+        #
+        # @param context [DocOpsLab::Dev] caller context
+        # @param target_filter [String, nil] restrict to entries whose target matches
+        # @return [Hash{String => Sourcerer::Sync::Cast::CastResult}]
+        def init_cast_targets context, target_filter: nil
+          castings, global_data = load_castings(context, target_filter)
+          return {} unless castings
+
+          puts '🆕 Initializing cast targets...'
+
+          results = {}
+          castings.each do |entry|
+            prime_path = resolve_prime(entry)
+            next unless prime_path
+
+            target_path = entry['target']
+
+            if File.exist?(target_path)
+              puts "  ⏭️  Skipped #{target_path} (already exists; use labdev:sync:templates to update)"
+              next
+            end
+
+            data   = build_data(global_data, entry)
+            result = Sourcerer::Sync.init(prime_path, target_path, data: data)
+
+            results[target_path] = result
+            report_result(result, init: true)
+          end
+
+          puts "✅ Initialized #{results.size} cast target(s)"
+          results
+        end
+
+        private
+
+        # Returns [entries_array, global_data_hash] from the manifest.
+        # When target_filter is given, entries is restricted to that single entry.
+        def load_castings context, target_filter
+          manifest = context.load_manifest
+          unless manifest
+            puts "❌ No manifest found at #{MANIFEST_PATH}"
+            return nil
+          end
+
+          templates_cfg = manifest['templates']
+          unless templates_cfg.is_a?(Hash)
+            puts '⚠️  No templates section configured in manifest'
+            return nil
+          end
+
+          castings = templates_cfg['manifest']
+          unless castings.is_a?(Array) && castings.any?
+            puts '⚠️  No entries configured under templates.manifest:'
+            return nil
+          end
+
+          global_data = templates_cfg['data'] || {}
+
+          if target_filter
+            castings = castings.select { |e| e['target'] == target_filter }
+            if castings.empty?
+              puts "❌ No casting matched target: #{target_filter}"
+              return nil
+            end
+          end
+
+          [castings, global_data]
+        end
+
+        # Build the Liquid data hash for a casting.
+        #
+        # All template variables live under the top-level +data+ key:
+        #   data.project.attributes  — document attributes from README.adoc
+        #   data.variables.<key>     — merged manifest variables (global + per-entry)
+        #
+        # Precedence: data.project.attributes < global variables < per-entry variables
+        def build_data global_data, entry
+          inner = { 'project' => { 'attributes' => DataUtils.project_attributes } }
+
+          vars = {}
+          vars.merge!(global_data['variables'] || {})
+
+          casting_data = entry['data'] || {}
+          vars.merge!(casting_data['variables'] || {})
+
+          inner['variables'] = vars
+          { 'data' => inner }
+        end
+
+        # Resolve the prime template path from a casting entry.
+        # Uses 'source' key for library-relative paths.
+        def resolve_prime entry
+          if entry['source']
+            lib_root = Library.root
+            unless lib_root
+              puts '  ❌ Library not available; run labdev:sync:library to fetch.'
+              return nil
+            end
+            path = File.join(lib_root, entry['source'])
+            return path if File.exist?(path)
+
+            puts "  ❌ Library source not found: #{entry['source']} (run labdev:sync:library)"
+          else
+            puts "  ❌ Entry for '#{entry['target']}' has no 'source' key"
+          end
+          nil
+        end
+
+        def report_result result, dry_run: false, init: false
+          target = result.target_path
+
+          result.errors.each   { |e| puts "  ❌ #{target}: #{e}" }
+          result.warnings.each { |w| puts "  ⚠️  #{target}: #{w}" }
+
+          return if result.errors.any?
+
+          if init
+            puts "  ✅ Initialized #{target}"
+          elsif dry_run
+            if result.diff && !result.diff.empty?
+              puts "  📋 #{target}: differences found"
+              result.diff.lines.first(10).each { |l| print "     #{l}" }
+              puts ''
+            else
+              puts "  ✓  #{target}: up to date"
+            end
+          elsif result.applied_changes.any?
+            puts "  ✅ #{target}: updated blocks: #{result.applied_changes.join(', ')}"
+          else
+            puts "  ✓  #{target}: up to date"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/config_manager.rb

@@ -5,9 +5,9 @@ module DocOpsLab
     module ConfigManager
       class << self
         def generate_vale_config _context, style_override: nil
-          base_config = File.join(CONFIG_VENDOR_DIR, 'vale.ini')
+          base_config = File.join(Paths.config_vendor_dir, 'vale.ini')
           project_config = '.config/vale.local.ini'
-          generated_config = CONFIG_PATHS[:vale]
+          generated_config = Paths::CONFIG_FILES[:vale]
 
           return false unless File.exist?(base_config)
 
@@ -34,9 +34,9 @@ module DocOpsLab
         end
 
         def generate_htmlproofer_config _context
-          base_config = File.join(CONFIG_VENDOR_DIR, 'htmlproofer.yml')
+          base_config = File.join(Paths.config_vendor_dir, 'htmlproofer.yml')
           project_config = '.config/htmlproofer.local.yml'
-          generated_config = CONFIG_PATHS[:htmlproofer]
+          generated_config = Paths::CONFIG_FILES[:htmlproofer]
 
           return false unless File.exist?(base_config)
 
@@ -59,9 +59,9 @@ module DocOpsLab
           config_paths = if config_path && File.exist?(config_path)
                            [config_path]
                          else
-                           [CONFIG_PATHS[:htmlproofer]]
+                           [Paths::CONFIG_FILES[:htmlproofer]]
                          end
-          config_paths << File.join(CONFIG_VENDOR_DIR, 'htmlproofer.yml') unless policy == 'replace'
+          config_paths << File.join(Paths.config_vendor_dir, 'htmlproofer.yml') unless policy == 'replace'
           config_path = config_paths.find { |path| File.exist?(path) }
 
           return unless config_path

data/lib/docopslab/dev/data_utils.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DocOpsLab
+  module Dev
+    # Utilities for loading and caching project-level data for use in
+    # Liquid template rendering (Sync/Cast) and other data-driven operations.
+    module DataUtils
+      class << self
+        # Lazily load and cache the README.adoc document attributes.
+        #
+        # Available in Liquid templates as +data.project.attributes.<key>+.
+        # Asciidoctor built-in attributes are filtered out; only user-defined
+        #  string attributes are returned.
+        #
+        # @return [Hash{String => String}]
+        def project_attributes
+          return @project_attributes if defined?(@project_attributes)
+
+          readme = 'README.adoc'
+          unless File.exist?(readme)
+            @project_attributes = {}
+            return @project_attributes
+          end
+
+          require 'sourcerer/asciidoc'
+          raw = Sourcerer::AsciiDoc.load_attributes(readme)
+          @project_attributes = raw.select do |k, v|
+            v.is_a?(String) && !v.empty? && !k.start_with?('asciidoctor')
+          end
+        rescue StandardError => e
+          warn "⚠️  Could not load README.adoc attributes: #{e.message}"
+          @project_attributes = {}
+        end
+
+        # Reset the cached project attributes (useful in tests or after file changes).
+        def reset_project_attributes!
+          remove_instance_variable(:@project_attributes) if defined?(@project_attributes)
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/docker_aware.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DocOpsLab
+  module Dev
+    # Detects and provides utilities for Docker container environments.
+    module DockerAware
+      class << self
+        # True if running inside a Docker container.
+        # Checks:
+        #   1. DOCOPSLAB_IN_DOCKER environment variable (set in Dockerfile)
+        #   2. /.dockerenv marker file (standard Docker indicator)
+        def running_in_docker?
+          ENV['DOCOPSLAB_IN_DOCKER'] == 'true' || File.exist?('/.dockerenv')
+        end
+
+        # True if Docker but without access to host's cache directory.
+        # This is the case when user runs: docker run -v "$(pwd):/workspace" ...
+        # without explicitly mounting ~/.cache/docopslab
+        def docker_without_cache?
+          running_in_docker? && !cache_mount_accessible?
+        end
+
+        # True if the Docker container can access the host's cache mount.
+        # Checks if /home/docops/.cache/docopslab exists and is readable.
+        def cache_mount_accessible?
+          cache_path = File.expand_path('~/.cache/docopslab')
+          File.exist?(cache_path) && File.directory?(cache_path) && File.readable?(cache_path)
+        rescue StandardError
+          false
+        end
+
+        # Workspace-relative cache path for Docker-only users.
+        # Returns path like /workspace/.docopslab-cache/
+        def workspace_cache_path
+          File.join('/workspace', '.docopslab-cache')
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/file_utils.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'pathname'
+require 'sourcerer/util/pathifier'
 
 module DocOpsLab
   module Dev
@@ -30,6 +31,18 @@ module DocOpsLab
               scripts << file if File.executable?(file) || FileUtilities.shell_shebang?(file)
             end
           end
+
+          # Also pick up extensionless files with a Bash-implying shebang
+          Dir.glob('**/*').each do |file|
+            next unless File.file?(file)
+            next unless File.extname(file).empty?
+            next if file.include?('/.vendor/')
+            next if file.include?('/node_modules/')
+            next unless FileUtilities.git_tracked_or_staged?(file)
+
+            scripts << file if FileUtilities.shell_shebang?(file)
+          end
+
           scripts.uniq.sort
         end
 
@@ -54,15 +67,13 @@ module DocOpsLab
 
           return [] unless lint_paths
 
+          pwd = Pathname.pwd
           files = []
           lint_paths.each do |path|
-            # If path is a directory, search recursively. Otherwise, it's a glob.
-            glob_pattern = File.directory?(path) ? File.join(path, '**', '*') : path
-            Dir.glob(glob_pattern).each do |file|
-              next unless File.file?(file)
-
-              # Normalize path by removing ./ prefix for consistent pattern matching
-              normalized = file.sub(%r{^\./}, '')
+            Sourcerer::Util::Pathifier.match(path).enum.each do |file|
+              # Normalize to a relative path for consistent pattern matching.
+              # Pathifier may return absolute paths, so we relativize unconditionally.
+              normalized = Pathname.new(file).expand_path.relative_path_from(pwd).to_s
               files << normalized
             end
           end

data/lib/docopslab/dev/git_branch.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'English'
+module DocOpsLab
+  module Dev
+    # Git branch safety utilities for Rake tasks
+    #
+    # Provides methods to safely handle branch switching by checking for:
+    # - Uncommitted changes (modified tracked files)
+    # - Untracked files that would conflict with target branch
+    #
+    # @example Basic usage
+    #   include DocOpsLab::Dev::GitBranch
+    #
+    #   current = git_current_branch
+    #   if git_safe_to_switch?('gh-pages')
+    #     system("git checkout gh-pages")
+    #   else
+    #     exit 1
+    #   end
+    #
+    # @example With custom error handling
+    #   git_ensure_clean_switch!('deploy-branch') do |conflicts|
+    #     puts "Found conflicts: #{conflicts.join(', ')}"
+    #   end
+    module GitBranch
+      # Get the current branch name
+      #
+      # @return [String] the current branch name
+      # @raise [RuntimeError] if not in a git repository
+      def git_current_branch
+        branch = `git branch --show-current 2>&1`.strip
+        raise 'Not in a git repository' if $CHILD_STATUS.exitstatus != 0
+
+        branch
+      end
+
+      # Check if working directory has uncommitted changes
+      #
+      # Uses `git status --porcelain` to detect:
+      # - Modified tracked files
+      # - Staged changes
+      # - Deleted files
+      #
+      # @return [Boolean] true if there are uncommitted changes
+      def git_has_uncommitted_changes?
+        !`git status --porcelain`.strip.empty?
+      end
+
+      # Get list of untracked files in working directory
+      #
+      # @return [Array<String>] list of untracked file paths
+      def git_untracked_files
+        `git ls-files --others --exclude-standard`.strip.split("\n")
+      end
+
+      # Get list of files in target branch
+      #
+      # @param branch [String] the target branch name
+      # @return [Array<String>] list of file paths in the branch
+      # @return [nil] if branch doesn't exist
+      def git_files_in_branch branch
+        # Check if branch exists
+        result = `git rev-parse --verify #{branch} 2>/dev/null`.strip
+        return nil if result.empty?
+
+        # List all files in the branch
+        `git ls-tree -r #{branch} --name-only`.strip.split("\n")
+      end
+
+      # Find untracked files that would conflict with target branch
+      #
+      # An untracked file conflicts if:
+      # - It exists in the working directory (untracked)
+      # - A file with the same path exists in the target branch
+      # - Switching branches would require overwriting the untracked file
+      #
+      # @param branch [String] the target branch name
+      # @return [Array<String>] list of conflicting file paths
+      # @return [nil] if target branch doesn't exist
+      def git_conflicting_files branch
+        branch_files = git_files_in_branch(branch)
+        return nil if branch_files.nil?
+
+        untracked = git_untracked_files
+        untracked & branch_files # Intersection
+      end
+
+      # Check if it's safe to switch to target branch
+      #
+      # Safe to switch if:
+      # - No uncommitted changes in tracked files
+      # - No untracked files that would conflict with target branch
+      #
+      # @param branch [String] the target branch name
+      # @param verbose [Boolean] whether to print detailed messages
+      # @return [Boolean] true if safe to switch
+      def git_safe_to_switch? branch, verbose: true
+        # Check for uncommitted changes
+        if git_has_uncommitted_changes?
+          puts '❌ You have uncommitted changes. Please commit or stash them first.' if verbose
+          puts "💡 Run 'git status' to see changes." if verbose
+          return false
+        end
+
+        # Check for conflicting untracked files
+        conflicts = git_conflicting_files(branch)
+
+        if conflicts.nil?
+          puts "❌ Target branch '#{branch}' does not exist." if verbose
+          return false
+        end
+
+        unless conflicts.empty?
+          if verbose
+            puts "❌ Untracked files would conflict with branch '#{branch}':"
+            conflicts.each { |f| puts "   - #{f}" }
+            puts '💡 Commit these files or remove them before switching branches.'
+          end
+          return false
+        end
+
+        true
+      end
+
+      # Ensure it's safe to switch branches, exit if not
+      #
+      # This is a convenience method that calls git_safe_to_switch?
+      # and exits with status 1 if not safe.
+      #
+      # @param branch [String] the target branch name
+      # @param verbose [Boolean] whether to print detailed messages
+      # @yield [conflicts] optional block to run if conflicts found
+      # @yieldparam conflicts [Array<String>] list of conflicting files
+      # @return [void]
+      def git_ensure_clean_switch! branch, verbose: true
+        return if git_safe_to_switch?(branch, verbose: verbose)
+
+        # If block given, call it with conflicts before exiting
+        if block_given?
+          conflicts = git_conflicting_files(branch) || []
+          yield(conflicts)
+        end
+
+        exit 1
+      end
+
+      # Execute a block on a different branch, then return to original
+      #
+      # Safely switches to target branch, executes block, then returns
+      # to original branch. Ensures clean state before switching.
+      #
+      # @param branch [String] the target branch to switch to
+      # @param verbose [Boolean] whether to print detailed messages
+      # @yield the block to execute on the target branch
+      # @return [Object] the return value of the block
+      # @raise [RuntimeError] if branch switch fails or block raises
+      #
+      # @example
+      #   git_on_branch('gh-pages') do
+      #     # Do work on gh-pages
+      #     FileUtils.cp_r('_site/*', '.')
+      #   end
+      #   # Automatically returns to original branch
+      def git_on_branch branch, verbose: true
+        original_branch = git_current_branch
+
+        # Safety check
+        git_ensure_clean_switch!(branch, verbose: verbose)
+
+        begin
+          puts "📦 Switching to #{branch} branch..." if verbose
+          system("git checkout #{branch}") or raise "Failed to checkout #{branch}"
+
+          # Execute the block
+          result = yield
+
+          result
+        ensure
+          # Always return to original branch
+          if git_current_branch != original_branch
+            puts "🔄 Returning to #{original_branch} branch..." if verbose
+            system("git checkout #{original_branch}")
+          end
+        end
+      end
+
+      # Get a summary of git working directory status
+      #
+      # @return [Hash] hash with :branch, :clean, :modified_count, :untracked_count
+      def git_status_summary
+        {
+          branch: git_current_branch,
+          clean: !git_has_uncommitted_changes?,
+          modified_count: `git status --porcelain`.strip.lines.count,
+          untracked_count: git_untracked_files.count
+        }
+      end
+    end
+  end
+end

data/lib/docopslab/dev/git_hooks.rb

@@ -9,8 +9,8 @@ module DocOpsLab
         def install_missing_hooks
           return unless Dir.exist?(hooks_dir)
 
-          Dir.glob("#{hooks_template_dir}/*.sh").each do |template_path|
-            hook_name = File.basename(template_path, '.sh')
+          Dir.glob("#{hooks_template_dir}/*").each do |template_path|
+            hook_name = File.basename(template_path)
             hook_path = File.join(hooks_dir, hook_name)
 
             next if File.exist?(hook_path)
@@ -27,8 +27,8 @@ module DocOpsLab
 
           updates_available = false
 
-          Dir.glob("#{hooks_template_dir}/*.sh").each do |template_path|
-            hook_name = File.basename(template_path, '.sh')
+          Dir.glob("#{hooks_template_dir}/*").each do |template_path|
+            hook_name = File.basename(template_path)
             hook_path = File.join(hooks_dir, hook_name)
 
             if File.exist?(hook_path)
@@ -55,8 +55,10 @@ module DocOpsLab
         def update_hooks_interactive
           return puts 'ℹ️  No .git directory found' unless Dir.exist?(hooks_dir)
 
-          Dir.glob("#{hooks_template_dir}/*.sh").each do |template_path|
-            hook_name = File.basename(template_path, '.sh')
+          hooks_to_update = []
+
+          Dir.glob("#{hooks_template_dir}/*").each do |template_path|
+            hook_name = File.basename(template_path)
             hook_path = File.join(hooks_dir, hook_name)
 
             if File.exist?(hook_path)
@@ -65,6 +67,8 @@ module DocOpsLab
 
               next if template_content == current_content
 
+              hooks_to_update << hook_name
+
               puts "🔄 #{hook_name} hook has updates available"
               puts "Current file exists at: #{hook_path}"
 
@@ -92,14 +96,15 @@ module DocOpsLab
               end
             end
           end
+          puts '✅ No hooks need updating.' if hooks_to_update.empty?
         end
 
         def list_hook_templates
           puts '📋 Available git hook templates:'
           puts ''
 
-          Dir.glob("#{hooks_template_dir}/*.sh").each do |template_path|
-            hook_name = File.basename(template_path, '.sh')
+          Dir.glob("#{hooks_template_dir}/*").each do |template_path|
+            hook_name = File.basename(template_path)
             hook_path = File.join(hooks_dir, hook_name)
 
             status = nil
@@ -120,7 +125,7 @@ module DocOpsLab
                             ''
                           end
 
-            puts "  #{hook_name}: #{status}"
+            puts "  - #{hook_name.ljust(15)} (#{status})"
             puts "    #{description}" unless description.empty?
           end
         end
@@ -128,11 +133,12 @@ module DocOpsLab
         private
 
         def hooks_template_dir
-          HOOKS_SOURCE_DIR
+          Library.ensure_available!
+          Library.resolve('hooks') || raise('Library hooks directory not found; run `labdev:sync:library`.')
         end
 
         def hooks_dir
-          HOOKS_DIR
+          Dev.hooks_dir
         end
       end
     end