docopslab-dev 0.1.0 → 0.2.0

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}"

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)

data/lib/docopslab/dev/skim.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'asciisourcerer'
+require 'sourcerer/util/pathifier'
+
+module DocOpsLab
+  module Dev
+    # Source skimming via Sourcerer::SourceSkim
+    module Skim
+      ADOC_EXTS = %w[.adoc .asc .ad .asciidoc].freeze
+      MD_EXTS   = %w[.md .markdown].freeze
+      ALL_EXTS  = (ADOC_EXTS + MD_EXTS).freeze
+
+      class << self
+        # Skim all supported file types (AsciiDoc + Markdown), format auto-detected.
+        def run path, form: nil, syntax: nil
+          run_with_format(path, exts: ALL_EXTS, form: form, syntax: syntax)
+        end
+
+        # Skim AsciiDoc source files only.
+        def run_adoc path, form: nil, syntax: nil
+          run_with_format(path, exts: ADOC_EXTS, form: form, syntax: syntax, default_forms: [:tree])
+        end
+
+        # Skim Markdown source files only, with optional upstream:local overlay support.
+        def run_md path, form: nil, syntax: nil
+          run_with_format(path, exts: MD_EXTS, form: form, syntax: syntax, overlay: true)
+        end
+
+        private
+
+        def run_with_format path, exts:, form: nil, syntax: nil, default_forms: nil, overlay: false
+          unless path
+            puts '❌ Path is required.'
+            puts 'Usage: bundle exec rake labdev:skim[path,form,syntax]'
+            return
+          end
+
+          forms      = form ? parse_forms(form) : default_forms
+          file_paths = overlay ? resolve_overlay_paths(path, exts) : resolve_paths(path, exts)
+
+          if file_paths.empty?
+            ext_desc = exts.size == 1 ? exts.first : exts.join(', ')
+            warn "No #{ext_desc} files found for: #{path}"
+            return
+          end
+
+          results = {}
+          cats = Sourcerer::SourceSkim::DEFAULT_CATEGORIES - [:attributes_custom]
+          file_paths.each do |fp|
+            skim_opts = { categories: cats }
+            skim_opts[:forms] = forms if forms
+            results[fp] = Sourcerer::SourceSkim.skim_file(fp, **skim_opts)
+          end
+          portable = JSON.parse(JSON.generate(results))
+
+          output_syntax = resolve_syntax(syntax, form)
+          puts output_syntax == :json ? JSON.pretty_generate(portable) : portable.to_yaml
+        end
+
+        # Resolve file paths with optional upstream:local overlay.
+        #
+        # When path_arg contains ':', split into upstream_dir:local_dir. Local files shadow
+        # upstream files that share the same relative path; local-only files are appended.
+        def resolve_overlay_paths path_arg, exts
+          parts = path_arg.split(':', 2).map(&:strip)
+          return resolve_paths(parts[0], exts) if parts.size == 1
+
+          upstream_dir, local_dir = parts
+          upstream_map = build_relative_map(upstream_dir, exts)
+          local_map    = build_relative_map(local_dir, exts)
+          upstream_map.merge(local_map).values
+        end
+
+        def build_relative_map dir_path, exts
+          dir_path = dir_path.chomp('/')
+          return {} unless File.directory?(dir_path)
+
+          abs_base = File.expand_path(dir_path)
+          Sourcerer::Util::Pathifier.match(dir_path).enum
+                                    .select { |p| exts.any? { |e| p.end_with?(e) } }
+                                    .each_with_object({}) do |abs_path, map|
+            map[abs_path.sub("#{abs_base}/", '')] = abs_path
+          end
+        end
+
+        def parse_forms form
+          form.split(',').map { |f| f.strip.to_sym }
+        end
+
+        def resolve_paths path, exts
+          result = Sourcerer::Util::Pathifier.match(path)
+          result.type == :dir ? result.enum.select { |p| exts.any? { |e| p.end_with?(e) } } : result.enum.to_a
+        end
+
+        def resolve_syntax syntax, form
+          return :yaml unless form
+
+          syntax = 'yaml' if syntax == 'yml'
+          puts
+          return syntax.to_sym if syntax
+
+          :json
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/spell_check.rb

@@ -146,8 +146,8 @@ module DocOpsLab
           require 'erb'
 
           unless agent_prompt
-            template_path = File.join(TEMPLATES_DIR, 'spellcheck.prompt.yml')
-            agent_prompt = File.read(template_path) if File.exist?(template_path)
+            template_path = Library.resolve('templates/spellcheck.prompt.yml')
+            agent_prompt = File.read(template_path) if template_path && File.exist?(template_path)
           end
 
           # Create the YAML content with ERB templating for better formatting

data/lib/docopslab/dev/sync_ops.rb

@@ -6,36 +6,35 @@ require 'pathname'
 
 module DocOpsLab
   module Dev
+    # rubocop:disable Metrics/ModuleLength
     module SyncOps
-      # rubocop :disable Metrics/ClassLength
+      # rubocop:disable Metrics/ClassLength
       class << self
         def install_vale_styles context
-          return unless File.exist?(CONFIG_PATHS[:vale]) && context.tool_available?('vale')
+          return unless File.exist?(Paths::CONFIG_FILES[:vale]) && context.tool_available?('vale')
 
-          puts "📚 Syncing Vale styles using Packages key in #{CONFIG_PATHS[:vale]} (local and remote packages)"
-          context.run_with_fallback('vale', "vale --config=#{CONFIG_PATHS[:vale]} sync")
+          puts "📚 Syncing Vale styles using Packages key in #{Paths::CONFIG_FILES[:vale]} (local and remote packages)"
+          context.run_with_fallback('vale', "vale --config=#{Paths::CONFIG_FILES[:vale]} sync")
         end
 
         def sync_vale_styles context, local: false
           puts '📚 Syncing Vale styles...'
 
-          styles_source_root = if context.lab_dev_mode?
-                                 # Running inside lab monorepo
-                                 'gems/docopslab-dev/assets/config-packs/vale'
-                               else
-                                 # Running from consumer project with path dependency
-                                 File.join(GEM_ROOT, 'assets', 'config-packs', 'vale')
-                               end
+          unless Library.available?
+            puts '❌ Library not available; run `labdev:sync:library` to fetch.'
+            return false
+          end
+          styles_source_root = Library.resolve('config-packs/vale')
+          unless styles_source_root
+            puts '❌ config-packs/vale not found in library; run `labdev:sync:library` to fetch.'
+            return false
+          end
           styles_dest_root = '.config/.vendor/vale/styles'
           FileUtils.mkdir_p(styles_dest_root)
 
           # Get the list of local styles from tools.yml
           begin
-            tools_yml_path = if context.lab_dev_mode?
-                               'gems/docopslab-dev/specs/data/tools.yml'
-                             else
-                               File.join(GEM_ROOT, 'specs', 'data', 'tools.yml')
-                             end
+            tools_yml_path = Dev.tools_def_path
 
             style_paths_array = YAML.load_file(tools_yml_path)
                                     .find { |t| t['slug'] == 'vale' }['packaging']['packages']
@@ -77,7 +76,7 @@ module DocOpsLab
           # If not local-only, also run Vale sync for remote styles
           unless local
             puts '📦 Syncing remote Vale packages...'
-            vale_config = CONFIG_PATHS[:vale]
+            vale_config = Paths::CONFIG_FILES[:vale]
             context.generate_vale_config unless File.exist?(vale_config)
             context.run_with_fallback('vale', "vale --config=#{vale_config} sync")
           end
@@ -92,6 +91,12 @@ module DocOpsLab
           docs_entries = manifest['docs']
           return false unless docs_entries.is_a?(Array)
 
+          lib_root = Library.root
+          unless lib_root
+            puts '❌ Library not available; run `labdev:sync:library` to fetch.'
+            return false
+          end
+
           puts '📚 Syncing documentation files...'
 
           synced_count = 0
@@ -107,16 +112,14 @@ module DocOpsLab
             next unless source_pattern
             next if synced # Only collect exclusions
 
-            # Resolve source file path
+            # Resolve source file path relative to library root
             if source_pattern.include?('*')
-              # Glob pattern for exclusions
-              source_glob = File.join(GEM_ROOT, source_pattern)
+              source_glob = File.join(lib_root, source_pattern)
               Dir.glob(source_glob).each do |source_file|
                 excluded_files.add(source_file) if File.file?(source_file)
               end
             else
-              # Single file exclusion
-              source_file = File.join(GEM_ROOT, source_pattern)
+              source_file = File.join(lib_root, source_pattern)
               excluded_files.add(source_file) if File.exist?(source_file)
             end
           end
@@ -134,8 +137,7 @@ module DocOpsLab
 
             # Check if source is a glob pattern
             if source_pattern.include?('*')
-              # Glob pattern; copy matching files
-              source_glob = File.join(GEM_ROOT, source_pattern)
+              source_glob = File.join(lib_root, source_pattern)
               matching_files = Dir.glob(source_glob)
 
               if matching_files.empty?
@@ -147,13 +149,18 @@ module DocOpsLab
                 next unless File.file?(source_file)
                 next if sources_checked.include?(source_file)
 
-                # Skip if explicitly excluded
                 if excluded_files.include?(source_file)
                   puts "  ⏭️  Skipped #{File.basename(source_file)} (explicitly excluded)"
                   next
                 end
 
-                # Determine target file path
+                # Guard: docs/agent/AGENTS.md was relocated to templates/AGENTS.markdown.
+                if source_file.end_with?('docs/agent/AGENTS.md')
+                  puts '  ⏭️  Skipped docs/agent/AGENTS.md \
+                        (relocated to templates/AGENTS.markdown; remove from manifest)'
+                  next
+                end
+
                 filename = File.basename(source_file)
                 target_file = File.join(target_path, filename)
 
@@ -163,11 +170,11 @@ module DocOpsLab
                 skipped_count += 1 if result == :skipped
               end
             else # Single file
-              source_file = File.join(GEM_ROOT, source_pattern)
+              source_file = File.join(lib_root, source_pattern)
 
               unless File.exist?(source_file)
                 puts "  ❌ Source file not found: #{source_file}"
-                puts "     Run 'bundle exec rake gemdo:gen_agent_docs' in DocOps/lab to generate docs"
+                puts "     Run 'bundle exec rake labdev:sync:library` then 'labdev:sync:docs' to refresh"
                 next
               end
 
@@ -179,6 +186,12 @@ module DocOpsLab
                 next
               end
 
+              # Guard: docs/agent/AGENTS.md was relocated to templates/AGENTS.markdown.
+              if source_file.end_with?('docs/agent/AGENTS.md')
+                puts '  ⏭️  Skipped docs/agent/AGENTS.md (relocated to templates/AGENTS.markdown; remove from manifest)'
+                next
+              end
+
               sources_checked << source_file
 
               result = copy_doc_file(source_file, target_path, synced: synced, force: force)
@@ -198,6 +211,52 @@ module DocOpsLab
           ScriptManager.sync_scripts
         end
 
+        def sync_templates context, force: false
+          manifest = context.load_manifest
+          return false unless manifest
+
+          template_entries = manifest['templates']
+          return false unless template_entries.is_a?(Array)
+
+          lib_root = Library.root
+          unless lib_root
+            puts '❌ Library not available; run `labdev:sync:library` to fetch.'
+            return false
+          end
+
+          puts '📄 Syncing template files...'
+
+          synced_count = 0
+          skipped_count = 0
+
+          template_entries.each do |entry|
+            source_rel = entry['source']
+            target_path = entry['target']
+            synced = entry.fetch('synced', false)
+
+            next unless source_rel && target_path
+
+            source_file = File.join(lib_root, source_rel)
+
+            unless File.exist?(source_file)
+              puts "  \u274c Template source not found: #{source_rel}"
+              puts '     Run `bundle exec rake labdev:sync:library` to fetch the latest library.'
+              next
+            end
+
+            result = copy_doc_file(source_file, target_path, synced: synced, force: force)
+            synced_count  += 1 if result == :copied
+            skipped_count += 1 if result == :skipped
+          end
+
+          puts "\u2705 Synced #{synced_count} template file(s)" if synced_count.positive?
+          if skipped_count.positive?
+            puts "\u2139\ufe0f  Skipped #{skipped_count} existing template(s) (use --force to overwrite)"
+          end
+
+          synced_count.positive? || skipped_count.positive?
+        end
+
         def sync_config_files context, tool_filter: :all, offline: false
           # Validate tool filter parameter
           unless tool_filter == :all || tool_filter.is_a?(String) || tool_filter.is_a?(Symbol)
@@ -222,8 +281,9 @@ module DocOpsLab
             return false
           end
 
-          unless Dir.exist?(CONFIG_PACKS_SOURCE_DIR)
-            puts '❌ No assets/config-packs directory found in gem'
+          config_packs_root = Library.resolve('config-packs')
+          unless config_packs_root && Dir.exist?(config_packs_root)
+            puts '❌ config-packs not found in library; run `labdev:sync:library` to fetch.'
             return false
           end
 
@@ -270,7 +330,7 @@ module DocOpsLab
                 next
               end
 
-              source_path = File.join(CONFIG_PACKS_SOURCE_DIR, source_rel)
+              source_path = File.join(config_packs_root, source_rel)
 
               unless File.exist?(source_path)
                 puts "  ❌ Source not found: #{source_rel}"
@@ -375,7 +435,7 @@ module DocOpsLab
           obsolete_files = []
           # Common vendor paths to check for obsolete files
           vendor_patterns = [
-            File.join(CONFIG_VENDOR_DIR, '**', '*')
+            File.join(Paths.config_vendor_dir, '**', '*')
           ]
           vendor_patterns.each do |pattern|
             Dir.glob(pattern).each do |file_path|
@@ -462,7 +522,8 @@ module DocOpsLab
           end
         end
       end
-      # rubocop :enable Metrics/ClassLength
+      # rubocop:enable Metrics/ClassLength
     end
+    # rubocop:enable Metrics/ModuleLength
   end
 end