docopslab-dev 0.1.0 → 0.3.0

data/lib/docopslab/dev/library.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+require 'shellwords'
+require 'tmpdir'
+require_relative 'manifest'
+require_relative 'library/cache'
+require_relative 'library/fetch'
+
+module DocOpsLab
+  module Dev
+    # Remote library fetch, cache, and resolution.
+    # Manages a host-wide asset cache at ~/.cache/docopslab/dev/library/ (native)
+    # or ./.docopslab-cache/ (Docker without cache mount).
+    #
+    # Docker Cache Strategy:
+    # - If running in Docker with host cache mounted (-v ~/.cache/docopslab:...):
+    #   uses host cache path (DockerAware.cache_mount_accessible? = true)
+    # - If running in Docker without cache mount: uses workspace-relative cache
+    #   (./.docopslab-cache/) which persists with the project
+    # - If running natively: uses ~/.cache/docopslab/ via XDG_CACHE_HOME
+    #
+    # Callers should use this module directly: Library.fetch!, Library.resolve(path), etc.
+    module Library
+      class << self
+        def fetch! config=nil
+          config ||= library_config_from_manifest
+          with_cache_root(config) { Fetch.call(config) }
+        end
+
+        # Fetch the library if the cache is absent or stale, then sync all
+        # manifest-driven content (docs, config files, templates, scripts) to
+        # local paths. This is the main entry point for `labdev:sync:library`.
+        def sync! force: false
+          config = library_config_from_manifest
+          with_cache_root(config) do
+            if local_path_active?(config)
+              puts "📚 Using local library at #{File.expand_path(config['local_path'])}"
+            elsif !force && Cache.available? && sha_current?(config)
+              puts "\u2705 Library cache is up to date (#{Cache.stored_head&.slice(0, 8)})"
+            else
+              puts Cache.available? ? '🔄 Library has updates; refreshing...' : '📥 Library cache not found; fetching...'
+              ok = Fetch.call(config)
+              unless ok
+                warn '⚠️  Library fetch failed. Using existing cache if available.'
+                raise 'Library unavailable.' unless available?
+              end
+            end
+
+            context = Dev
+            SyncOps.sync_config_files(context)
+            SyncOps.sync_docs(context, force: force)
+            SyncOps.sync_templates(context, force: force)
+            SyncOps.sync_scripts(context)
+          end
+        end
+
+        # Copy a local library directory into the host cache and sync content to
+        # manifest-configured paths. Intended for development workflows where
+        # assets live in the +lab+ monorepo (.library/ or library/current/) and
+        # have not yet been published to the remote branch.
+        #
+        # Resolution order for +source_path+:
+        #   1. Explicit argument (task arg or direct call)
+        #   2. manifest +library.local_path+ (resolved relative to cwd)
+        #   3. .library/ in the current working directory
+        #   4. ../lab/.library/ relative to cwd (downstream-project fallback)
+        #
+        # A minimal catalog.json is generated into a staging copy if the source
+        # directory does not already contain one.
+        def stage! source_path: nil
+          resolved = resolve_stage_source(source_path)
+          unless resolved
+            warn '⚠️  No local library path found. ' \
+                 "Pass a path, or set library.local_path in #{Dev::MANIFEST_PATH}."
+            return false
+          end
+
+          puts "📦 Staging local library from #{resolved}..."
+
+          Dir.mktmpdir('docopslab-stage-') do |tmpdir|
+            dest = File.join(tmpdir, 'stage')
+            FileUtils.cp_r(resolved, dest)
+            ensure_catalog!(dest)
+            Cache.write!(dest)
+          end
+
+          puts "✅ Local library staged to #{Cache.current_path}"
+
+          context = Dev
+          SyncOps.sync_config_files(context)
+          SyncOps.sync_docs(context, force: true)
+          SyncOps.sync_templates(context, force: true)
+          SyncOps.sync_scripts(context)
+          true
+        rescue StandardError => e
+          warn "⚠️  Stage failed: #{e.message}"
+          false
+        end
+
+        def cached_path
+          Cache.current_path
+        end
+
+        # Returns the effective library root directory (nil if unavailable).
+        # Does not auto-fetch; call ensure_available! first if needed.
+        # Resolution order mirrors resolve():
+        #   1. XDG host cache  2. local_path from manifest
+        def root
+          return Cache.current_path if Cache.available?
+
+          lp = Dev.load_manifest&.dig('library', 'local_path')
+          return File.expand_path(lp) if lp && File.exist?(File.join(lp, 'catalog.json'))
+
+          nil
+        end
+
+        # Returns the absolute path to a cached file, or nil if absent.
+        # Resolution order:
+        #   1. XDG host cache (~/.cache/docopslab/dev/library/current/)
+        #   2. local_path from manifest (dev/monorepo fallback, e.g. .library/)
+        def resolve relative_path
+          if Cache.available?
+            full_path = File.join(Cache.current_path, relative_path)
+            return full_path if File.exist?(full_path)
+          end
+
+          # local_path fallback for monorepo dev and offline use
+          lp = Dev.load_manifest&.dig('library', 'local_path')
+          if lp
+            local_full = File.expand_path(File.join(lp, relative_path))
+            return local_full if File.exist?(local_full)
+          end
+
+          nil
+        end
+
+        # True if a library is available via cache or local_path fallback.
+        def available?
+          return true if Cache.available?
+
+          lp = Dev.load_manifest&.dig('library', 'local_path')
+          !!(lp && File.exist?(File.join(lp, 'catalog.json')))
+        end
+
+        # Ensure the library is available, auto-fetching if necessary.
+        # Returns true if available after the call; raises on failure.
+        def ensure_available!
+          return true if available?
+
+          puts '📥 Library cache not found; fetching now...'
+          ok = fetch!
+          return true if ok && available?
+
+          lp = Dev.load_manifest&.dig('library', 'local_path')
+          if lp && Dir.exist?(lp)
+            warn "⚠️  Remote fetch failed; using local_path fallback: #{lp}"
+            return true
+          end
+
+          raise 'Library unavailable. Run `bundle exec rake labdev:sync:library` to fetch it.'
+        end
+
+        def status
+          Cache.status
+        end
+
+        def rollback!
+          if Cache.rollback!
+            puts "✅ Library rolled back to previous snapshot at #{Cache.current_path}"
+            true
+          else
+            warn '⚠️  No previous library snapshot available for rollback.'
+            false
+          end
+        end
+
+        def print_status
+          s = status
+          if s[:available]
+            puts "📚 Library cache: #{s[:cache_path]}"
+            puts "   Version    : #{s[:version] || '(unknown)'}"
+            puts "   Ref        : #{s[:ref] || '(unknown)'}"
+            puts "   Generated  : #{s[:generated_at] || '(unknown)'}"
+            puts "   Previous   : #{s[:has_previous] ? 'yes' : 'none'}"
+          else
+            puts "⚠️  No library cache found at #{s[:cache_path]}"
+            lp = Dev.load_manifest&.dig('library', 'local_path')
+            if lp && File.exist?(File.join(lp, 'catalog.json'))
+              puts "   Local path : #{File.expand_path(lp)} (active fallback)"
+            else
+              puts '   Run `bundle exec rake labdev:sync:library` to fetch.'
+            end
+          end
+        end
+
+        # Compare manifest catalog entries against the cached library files
+        # Falls back to an on-repo local path if provided in the manifest
+        def print_catalog_comparison manifest = nil
+          manifest ||= Dev.load_manifest
+          lib_cfg = manifest && manifest['library']
+
+          if lib_cfg.nil? || lib_cfg.empty?
+            puts "ℹ️  No `library` block found in #{Dev.manifest_path} (or it's empty)."
+            return
+          end
+
+          catalog = lib_cfg.dig('catalog', 'overrides') || lib_cfg['catalog'] || lib_cfg['catalog_overrides']
+
+          unless catalog && !catalog.empty?
+            puts 'ℹ️  No catalog overrides found in manifest.library.catalog; nothing to compare.'
+            return
+          end
+
+          puts '🔎 Comparing manifest catalog entries to cached library files...'
+
+          entries = []
+          case catalog
+          when Array
+            entries = catalog
+          when Hash
+            catalog.each do |k, v|
+              entries << if v.is_a?(String)
+                           v
+                         elsif v.is_a?(Hash) && v['path']
+                           v['path']
+                         else
+                           k
+                         end
+            end
+          else
+            puts "⚠️  Unrecognized catalog format: #{catalog.class}. Skipping detailed compare."
+            return
+          end
+
+          missing = []
+          present = []
+
+          entries.each do |rel_path|
+            rel = rel_path.to_s.sub(%r{^/}, '')
+            resolved = resolve(rel)
+
+            # Fallback to on-repo local path if provided
+            if resolved.nil? && lib_cfg['local_path']
+              repo_local = File.join(Dir.pwd, lib_cfg['local_path'].to_s, rel)
+              resolved = File.exist?(repo_local) ? repo_local : nil
+            end
+
+            if resolved
+              present << { path: rel, full: resolved }
+            else
+              missing << rel
+            end
+          end
+
+          if present.any?
+            puts "✅ Found #{present.size} catalog entries in the cache or local path:"
+            present.each do |p|
+              puts "  - #{p[:path]} -> #{p[:full]}"
+            end
+          end
+
+          if missing.any?
+            puts "❌ Missing #{missing.size} catalog entries in the cache/local path:"
+            missing.each do |m|
+              puts "  - #{m}"
+            end
+          else
+            puts '✅ All catalog entries present in cache/local path.'
+          end
+        end
+
+        private
+
+        def sha_current? config
+          remote = Fetch.remote_head(config)
+          return Cache.fresh? unless remote # network unavailable; fall back to TTL
+
+          Cache.stored_head == remote
+        end
+
+        # True when local_path is configured and its catalog is present on disk.
+        # When active, sync! uses the local directory directly and skips the
+        # remote SHA check; the caller (library maintainer) manages it locally.
+        def local_path_active? config
+          lp = config['local_path']
+          lp && File.exist?(File.join(File.expand_path(lp), 'catalog.json'))
+        end
+
+        def with_cache_root(config, &)
+          cr = config.dig('sync', 'cache_root')
+          # Auto-derive from local_path when no explicit cache_root is set.
+          # local_path points to the 'current' snapshot dir, so its parent is
+          # the cache root (mirrors Cache::XDG_CACHE_SUBPATH layout).
+          cr = File.join(File.expand_path(config['local_path']), '..') if cr.nil? && local_path_active?(config)
+
+          # In Docker without access to host cache, use workspace-local cache
+          cr = DockerAware.workspace_cache_path if cr.nil? && DockerAware.docker_without_cache?
+
+          Cache.with_root_override(cr ? File.expand_path(cr) : nil, &)
+        end
+
+        def library_config_from_manifest
+          Dev.load_manifest&.dig('library') || {}
+        end
+
+        # Resolve the source directory for stage! using the priority chain:
+        #   explicit arg → manifest local_path → .library/ in cwd → ../lab/.library/
+        def resolve_stage_source explicit_path
+          candidates = []
+          candidates << File.expand_path(explicit_path) if explicit_path
+
+          lp = library_config_from_manifest['local_path']
+          candidates << File.expand_path(lp) if lp
+
+          candidates << File.join(Dir.pwd, '.library')
+          candidates << File.expand_path(File.join(Dir.pwd, '..', 'lab', '.library'))
+
+          candidates.find { |p| Dir.exist?(p) }
+        end
+
+        # Write a minimal catalog.json into +dir+ if one is not already present.
+        def ensure_catalog! dir
+          catalog_file = File.join(dir, 'catalog.json')
+          return if File.exist?(catalog_file)
+
+          files = Dir.glob("#{dir}/**/*").reject { |f| File.directory?(f) }
+                     .map { |f| f.delete_prefix("#{dir}/") }
+          catalog = {
+            'library_version' => 'local',
+            'library_ref'     => 'local-stage',
+            'generated_at'    => Time.now.utc.iso8601,
+            'files'           => files
+          }
+          File.write(catalog_file, JSON.generate(catalog))
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/linters.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'open3'
+require 'pathname'
+require 'sourcerer/util/pathifier'
 
 module DocOpsLab
   module Dev
@@ -9,9 +11,9 @@ module DocOpsLab
         def run_rubocop context, file_path=nil, opts_string=''
           context.generate_rubocop_config if context.respond_to?(:generate_rubocop_config)
 
-          rubocop_config_file = CONFIG_PATHS[:rubocop]
+          rubocop_config_file = Paths::CONFIG_FILES[:rubocop]
           unless File.exist?(rubocop_config_file)
-            rubocop_config_file = RUBOCOP_CONFIG_PATH # Fallback to vendor config
+            rubocop_config_file = File.join(Paths.config_vendor_dir, 'rubocop.yml') # Fallback to vendor config
           end
 
           unless File.exist?(rubocop_config_file)
@@ -57,9 +59,9 @@ module DocOpsLab
         end
 
         def run_rubocop_with_filter _context, filter_name
-          rubocop_config_file = CONFIG_PATHS[:rubocop]
+          rubocop_config_file = Paths::CONFIG_FILES[:rubocop]
           unless File.exist?(rubocop_config_file)
-            rubocop_config_file = RUBOCOP_CONFIG_PATH # Fallback to vendor config
+            rubocop_config_file = File.join(Paths.config_vendor_dir, 'rubocop.yml') # Fallback to vendor config
           end
 
           unless File.exist?(rubocop_config_file)
@@ -88,7 +90,16 @@ module DocOpsLab
           puts "🐚 Running ShellCheck on #{running_on}"
 
           shell_scripts = if scope == :file
-                            File.exist?(file_path) ? [file_path] : []
+                            result = Sourcerer::Util::Pathifier.match(file_path)
+                            if result.type == :file
+                              result.enum.to_a
+                            else
+                              result.enum.select do |f|
+                                ext = File.extname(f)
+                                ext.match?(/\.(sh|bash)$/) ||
+                                  (ext.empty? && FileUtilities.shell_shebang?(f))
+                              end.sort
+                            end
                           else
                             context.find_shell_scripts
                           end
@@ -109,7 +120,14 @@ module DocOpsLab
               success = false
               passed = false
             end
-            cmd = "shellcheck --severity=warning #{opts_string} --rcfile=.config/shellcheckrc #{script}".strip
+            # Relativize absolute paths so the command works both natively and inside
+            # Docker (which mounts $(pwd) as /workspace and sets -w /workspace).
+            script_arg = if script.start_with?('/')
+                           Pathname.new(script).relative_path_from(Pathname.new(Dir.pwd)).to_s
+                         else
+                           script
+                         end
+            cmd = "shellcheck --severity=warning #{opts_string} --rcfile=.config/shellcheckrc #{script_arg}".strip
             shellcheck = context.run_with_fallback('shellcheck', cmd)
             unless shellcheck
               success = false
@@ -183,7 +201,7 @@ module DocOpsLab
           puts '  ✅ Vale config up to date' unless context.generate_vale_config(style_override: style_override)
 
           # Use the generated config file
-          config_file = CONFIG_PATHS[:vale]
+          config_file = Paths::CONFIG_FILES[:vale]
 
           unless File.exist?(config_file)
             puts "❌ No Vale config found. Run 'labdev:sync:all' to generate one."
@@ -207,7 +225,33 @@ module DocOpsLab
 
           # Find AsciiDoc files to check, excluding vendor/ignored directories
           if scope == :file
-            asciidoc_files = [file_path]
+            path_result = Sourcerer::Util::Pathifier.match(file_path)
+            if path_result.type == :file
+              asciidoc_files = [file_path]
+            else
+              # Directory or glob: enumerate files and apply ext/skip filters from manifest,
+              # so that skip patterns (ex: in docopslab-dev.yml) are respected even when a
+              # specific directory or glob is passed via the task argument.
+              path_config = context.get_path_config('vale')
+              skip_paths = path_config[:skip] || []
+              exts = path_config[:exts] || []
+              pwd = Pathname.pwd
+              asciidoc_files = path_result.enum.select do |f|
+                normalized = Pathname.new(f).expand_path.relative_path_from(pwd).to_s
+                if exts && !exts.empty?
+                  ext = File.extname(f).delete_prefix('.')
+                  next false unless exts.include?(ext)
+                end
+                next false if skip_paths.any? { |p| FileUtilities.file_matches_ignore_pattern?(normalized, p) }
+
+                true
+              end.sort
+              if asciidoc_files.empty?
+                puts "📄 No AsciiDoc files found to check in #{file_path}"
+                return true
+              end
+              puts "📄 Found #{asciidoc_files.length} AsciiDoc file(s) to check in #{file_path}"
+            end
           else
             asciidoc_files = context.find_asciidoc_files
             if asciidoc_files.empty?
@@ -364,18 +408,25 @@ module DocOpsLab
           results.values.all?
         end
 
-        def run_rubocop_auto_fix _context, path: nil
+        def run_rubocop_auto_fix context, path: nil
           puts '👮 Running RuboCop auto-correction...'
 
-          unless File.exist?(RUBOCOP_CONFIG_PATH)
+          context.generate_rubocop_config if context.respond_to?(:generate_rubocop_config)
+
+          rubocop_config_file = Paths::CONFIG_FILES[:rubocop]
+          unless File.exist?(rubocop_config_file)
+            rubocop_config_file = File.join(Paths.config_vendor_dir, 'rubocop.yml') # Fallback to vendor config
+          end
+
+          unless File.exist?(rubocop_config_file)
             puts "❌ No RuboCop config found. Run 'labdev:init' to create one."
             return false
           end
 
-          puts "📄 Using config: #{RUBOCOP_CONFIG_PATH}"
+          puts "📄 Using config: #{rubocop_config_file}"
 
           # Build command with optional path
-          cmd = "bundle exec rubocop --config #{RUBOCOP_CONFIG_PATH} --autocorrect-all"
+          cmd = "bundle exec rubocop --config #{rubocop_config_file} --autocorrect-all"
           if path
             cmd += " #{path}"
             puts "📄 Targeting path: #{path}"
@@ -437,10 +488,17 @@ module DocOpsLab
         def check_shebang file_path
           return false unless File.exist?(file_path)
 
-          first_line = File.open(file_path, &:readline).strip
+          lines = File.readlines(file_path).map(&:strip)
+          return false if lines.empty?
+
+          first_line = lines[0]
+          second_line = lines[1]
+
+          # If second line has shellcheck directive for sh, require sh shebang
+          return first_line == '#!/bin/sh' if second_line == '# shellcheck shell=sh'
+
+          # Otherwise, require bash shebang
           first_line == '#!/usr/bin/env bash'
-        rescue EOFError
-          false
         rescue StandardError => e
           puts "⚠️  Error checking shebang for #{file_path}: #{e.message}"
           false

data/lib/docopslab/dev/manifest.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module DocOpsLab
+  module Dev
+    # Thin wrapper around the project manifest (.config/docopslab-dev.yml).
+    # Shared by tools, sync, and library operations that need manifest data.
+    module Manifest
+      class << self
+        # Load a project manifest YAML file.
+        # Returns the parsed hash or nil if the file is absent or unreadable.
+        def load path=Dev::MANIFEST_PATH
+          return nil unless File.exist?(path)
+
+          YAML.load_file(path)
+        rescue StandardError
+          nil
+        end
+
+        # True if data is a non-empty Hash.
+        def valid? data
+          data.is_a?(Hash) && !data.empty?
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/paths.rb

@@ -9,23 +9,6 @@ module DocOpsLab
         File.expand_path('../../..', __dir__)
       end
 
-      # Asset directories in gem
-      def self.gem_assets
-        File.join(gem_root, 'assets')
-      end
-
-      def self.gem_config_packs
-        File.join(gem_assets, 'config-packs')
-      end
-
-      def self.gem_hooks
-        File.join(gem_assets, 'hooks')
-      end
-
-      def self.gem_scripts
-        File.join(gem_assets, 'scripts')
-      end
-
       # Config vendor directory (where config packs are synced to)
       def self.config_vendor_dir
         '.config/.vendor/docopslab'

data/lib/docopslab/dev/script_manager.rb

@@ -9,8 +9,13 @@ module DocOpsLab
         def sync_scripts
           puts '📜 Syncing common scripts from DocOps Lab...'
 
-          unless Dir.exist?(SCRIPTS_SOURCE_DIR)
-            puts '❌ No scripts directory found in gem'
+          unless Library.available?
+            puts '❌ Library not available; run `labdev:sync:library` to fetch.'
+            return false
+          end
+          scripts_source = Library.resolve('scripts')
+          unless scripts_source && Dir.exist?(scripts_source)
+            puts '❌ scripts not found in library; run `labdev:sync:library` to fetch.'
             return false
           end
 
@@ -20,7 +25,7 @@ module DocOpsLab
 
           synced_count = 0
 
-          Dir.glob("#{SCRIPTS_SOURCE_DIR}/*").each do |script_path|
+          Dir.glob("#{scripts_source}/*").each do |script_path|
             next unless File.file?(script_path)
 
             script_name = File.basename(script_path)
@@ -47,14 +52,15 @@ module DocOpsLab
         end
 
         def list_script_templates
-          unless Dir.exist?(SCRIPTS_SOURCE_DIR)
-            puts '❌ No scripts directory found in gem'
+          scripts_source = Library.resolve('scripts')
+          unless scripts_source && Dir.exist?(scripts_source)
+            puts '❌ scripts not found in library; run `labdev:sync:library` to fetch.'
             return false
           end
 
           puts '📜 Available script templates:'
 
-          Dir.glob("#{SCRIPTS_SOURCE_DIR}/*").each do |script_path|
+          Dir.glob("#{scripts_source}/*").each do |script_path|
             next unless File.file?(script_path)
 
             script_name = File.basename(script_path)