docopslab-dev 0.1.0 → 0.3.0

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

data/lib/docopslab/dev/tasks.rb

@@ -54,11 +54,6 @@ module DocOpsLab
               Dev.check_standard_rake_tasks
             end
 
-            desc desc_for('check:updates')
-            task :updates do
-              Dev.check_hook_updates
-            end
-
             desc desc_for('check:all')
             task :all do
               Rake::Task['labdev:check:env'].invoke
@@ -89,6 +84,11 @@ module DocOpsLab
                 puts '⚠️  Agent docs sync skipped or failed'
               end
             end
+
+            desc desc_for('init:templates')
+            task :templates do
+              CastOps.init_cast_targets(Dev)
+            end
           end
 
           # ============================================================
@@ -135,9 +135,10 @@ module DocOpsLab
             # end
 
             desc desc_for('run:shellcheck')
-            task :shellcheck, [:opts] => [] do |_t, args|
+            task :shellcheck, %i[path opts] => [] do |_t, args|
+              path = args[:path]
               opts = args[:opts] || ''
-              Dev.run_shellcheck(nil, opts)
+              Dev.run_shellcheck(path, opts)
             end
 
             desc desc_for('run:actionlint')
@@ -167,6 +168,13 @@ module DocOpsLab
               Dev.sync_docs(force: true)
             end
 
+            desc desc_for('sync:templates')
+            task :templates, %i[path dry] => [] do |_t, args|
+              target = args[:path]
+              dry    = args[:dry].to_s.downcase == 'dry'
+              CastOps.sync_cast_targets(Dev, target_filter: target, dry_run: dry)
+            end
+
             namespace :styles do
               desc desc_for('sync:styles:local')
               task :local do
@@ -210,11 +218,22 @@ module DocOpsLab
 
             desc desc_for('sync:all')
             task :all do
-              Dev.sync_config_files
-              Dev.sync_scripts
-              Dev.sync_docs
+              Library.sync!
               Dev.install_missing_hooks
               Dev.sync_vale_styles
+              CastOps.sync_cast_targets(Dev)
+            end
+
+            desc desc_for('sync:library')
+            task :library do
+              Library.sync!
+            end
+
+            namespace :library do
+              desc desc_for('sync:library:stage')
+              task :stage, [:path] => [] do |_t, args|
+                Library.stage!(source_path: args[:path])
+              end
             end
           end
 
@@ -262,17 +281,12 @@ module DocOpsLab
 
             desc desc_for('lint:docs')
             task :docs, %i[path rule opts] => [] do |_t, args|
-              path = args[:path]
+              path = args[:path] || '.'
               rule = args[:rule]
               opts = args[:opts]
 
-              if path || rule || opts
-                filter = rule ? ".Name==#{rule}" : nil
-                target = path || nil
-                Dev.run_vale(target, opts || '', filter: filter)
-              else
-                Dev.run_linter_group('AsciiDoc', %w[vale])
-              end
+              filter = rule ? ".Name==#{rule}" : nil
+              Dev.run_vale(path, opts || '', filter: filter)
             end
 
             desc desc_for('lint:html')
@@ -398,6 +412,27 @@ module DocOpsLab
             Help.show_task_help('heal')
           end
 
+          # ============================================================
+          # SKIM tasks; Skim source files for machine-oriented outlines
+          # ============================================================
+
+          desc desc_for('skim')
+          task :skim, %i[path form syntax] => [] do |_t, args|
+            Skim.run(args[:path], form: args[:form], syntax: args[:syntax])
+          end
+
+          namespace :skim do
+            desc desc_for('skim:adoc')
+            task :adoc, %i[path form syntax] => [] do |_t, args|
+              Skim.run_adoc(args[:path], form: args[:form], syntax: args[:syntax])
+            end
+
+            desc desc_for('skim:md')
+            task :md, %i[path form syntax] => [] do |_t, args|
+              Skim.run_md(args[:path], form: args[:form], syntax: args[:syntax])
+            end
+          end
+
           # ============================================================
           # SHOW and HELP tasks; Display information
           # ============================================================
@@ -427,6 +462,11 @@ module DocOpsLab
 
               Dev.show_lint_rule(tool, rule)
             end
+
+            desc desc_for('show:library')
+            task :library do
+              Library.print_status
+            end
           end
 
           desc desc_for('help')

data/lib/docopslab/dev/version.rb

@@ -2,7 +2,7 @@
 
 module DocOpsLab
   module Dev
-    VERSION = '0.1.0'
+    VERSION = '0.3.0'
     RUBY_TARGET = '3.2.7'
   end
 end