docopslab-dev 0.1.0 → 0.2.0

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.2.0'
     RUBY_TARGET = '3.2.7'
   end
 end

data/lib/docopslab/dev.rb

@@ -8,16 +8,22 @@ require 'pathname'
 require 'shellwords'
 require_relative 'dev/version' # includes RUBY_TARGET
 require_relative 'dev/paths'
+require_relative 'dev/manifest'
 require_relative 'dev/spell_check'
 require_relative 'dev/log_parser'
+require_relative 'dev/skim'
 require_relative 'dev/tasks'
 require_relative 'dev/git_hooks'
 require_relative 'dev/tool_execution'
+require_relative 'dev/git_branch'
 require_relative 'dev/linters'
 require_relative 'dev/config_manager'
 require_relative 'dev/file_utils'
 require_relative 'dev/script_manager'
+require_relative 'dev/library'
 require_relative 'dev/sync_ops'
+require_relative 'dev/data_utils'
+require_relative 'dev/cast_ops'
 require_relative 'dev/checkers'
 require_relative 'dev/initializer'
 require_relative 'dev/auto_fix_asciidoc'
@@ -37,45 +43,74 @@ module DocOpsLab
       end
     end
 
-    # Path constants
-    # Project paths (local/runtime)
+    # Path constants (Backwards compatibility)
     MANIFEST_PATH = '.config/docopslab-dev.yml'
-    CONFIG_VENDOR_DIR = Paths.config_vendor_dir
-    HOOKS_DIR = '.git/hooks'
-
-    # Runtime/generated config files (merged from base + local)
-    CONFIG_PATHS = Paths::CONFIG_FILES
-
-    # Shorthand for rubocop (most commonly referenced)
-    RUBOCOP_CONFIG_PATH = CONFIG_PATHS[:rubocop]
-
-    # Gem source paths (assets bundled with gem)
-    MANIFEST_DEF_PATH = File.join(GEM_ROOT, 'specs', 'data', 'default-manifest.yml')
-    TOOLS_DEF_PATH = File.join(GEM_ROOT, 'specs', 'data', 'tools.yml')
-    CONFIG_PACKS_SOURCE_DIR = Paths.gem_config_packs
-    SCRIPTS_SOURCE_DIR = Paths.gem_scripts
-    HOOKS_SOURCE_DIR = Paths.gem_hooks
-    TEMPLATES_DIR = File.join(GEM_ROOT, 'assets', 'templates')
-    GITIGNORE_STUB_SOURCE_PATH = File.join(TEMPLATES_DIR, 'gitignore')
-    GEMFILE_STUB_SOURCE_PATH = File.join(TEMPLATES_DIR, 'Gemfile')
-    RAKEFILE_STUB_SOURCE_PATH = File.join(TEMPLATES_DIR, 'Rakefile')
-
-    # Cached data
-    @manifest = nil
-    @tools_data = nil
+    XDG_CACHE_SUBPATH = 'docopslab/dev/library'
 
     class << self
       attr_accessor :manifest, :tools_data
+      attr_writer :manifest_path, :xdg_cache_subpath
 
-      # Common Utility
+      def manifest_path
+        @manifest_path || MANIFEST_PATH
+      end
+
+      def xdg_cache_subpath
+        @xdg_cache_subpath || XDG_CACHE_SUBPATH
+      end
+
+      # Upstream library defaults
+      def default_library_repo
+        'DocOps/lab'
+      end
+
+      def default_library_branch
+        'labdev-library'
+      end
+
+      # Project paths (local/runtime)
+      def config_vendor_dir
+        Paths.config_vendor_dir
+      end
+
+      def hooks_dir
+        '.git/hooks'
+      end
+
+      # Runtime/generated config files (merged from base + local)
+      def config_paths
+        Paths::CONFIG_FILES
+      end
+
+      # Shorthand for rubocop (most commonly referenced)
+      def rubocop_config_path
+        config_paths[:rubocop]
+      end
+
+      # Gem data paths (bundled with gem in specs/data/)
+      def manifest_def_path
+        File.join(GEM_ROOT, 'specs', 'data', 'default-manifest.yml')
+      end
+
+      def tools_def_path
+        File.join(GEM_ROOT, 'specs', 'data', 'tools.yml')
+      end
+
+      # Asset paths are resolved at runtime from the remote library cache.
+      # Use Library.resolve('config-packs/...'), Library.resolve('templates/...') etc.
+      def library_path subpath=nil
+        return Library::Cache.current_path unless subpath
+
+        File.join(Library::Cache.current_path, subpath)
+      end
 
       def load_manifest force_reload: false
         return @manifest if @manifest && !force_reload
 
-        @manifest = YAML.load_file(MANIFEST_PATH) if File.exist?(MANIFEST_PATH)
+        @manifest = YAML.load_file(manifest_path) if File.exist?(manifest_path)
         @manifest
       rescue StandardError => e
-        warn "Failed to load manifest: #{e.message}"
+        warn "Failed to load manifest at #{manifest_path}: #{e.message}"
         nil
       end
 
@@ -83,8 +118,8 @@ module DocOpsLab
         return @tools_data if @tools_data
 
         @tools_data = begin
-          if File.exist?(TOOLS_DEF_PATH)
-            YAML.load_file(TOOLS_DEF_PATH)
+          if File.exist?(tools_def_path)
+            YAML.load_file(tools_def_path)
           else
             []
           end
@@ -205,6 +240,10 @@ module DocOpsLab
         SyncOps.sync_docs(self, force: force)
       end
 
+      def sync_templates force: false
+        SyncOps.sync_templates(self, force: force)
+      end
+
       # Checkers & Finders
 
       def tool_available? tool_name
@@ -317,8 +356,9 @@ module DocOpsLab
       end
 
       def run_vale file_path=nil, opts_string='', output_format: :cli, filter: nil, style_override: nil
-        Linters.run_vale self, file_path, opts_string, output_format: output_format, filter: filter,
-style_override: style_override
+        Linters.run_vale(
+          self, file_path, opts_string,
+          output_format: output_format, filter: filter, style_override: style_override)
       end
 
       def lint_file file_path
@@ -357,12 +397,12 @@ style_override: style_override
           puts "❌ Vale rule file not found: #{style_path}"
           return
         end
-        config = File.read(CONFIG_PATHS[:vale])
+        config = File.read(Paths::CONFIG_FILES[:vale])
         config.lines.each do |line|
           next unless line.strip.start_with?("#{package}.#{rule_name} =")
 
           rule_setting = line.strip.split('=', 2).last.strip
-          puts "⚙️  Rule setting from #{CONFIG_PATHS[:vale]}: '#{rule_setting}'"
+          puts "⚙️  Rule setting from #{Paths::CONFIG_FILES[:vale]}: '#{rule_setting}'"
           break
         end
         unless File.exist?(style_path)
@@ -376,7 +416,7 @@ style_override: style_override
 
       def print_cop rule
         puts "📄 RuboCop cop documentation for: #{rule}"
-        cmd = "bundle exec rubocop --show-cops #{rule} --config #{RUBOCOP_CONFIG_PATH}"
+        cmd = "bundle exec rubocop --show-cops #{rule} --config #{File.join(Paths.config_vendor_dir, 'rubocop.yml')}"
         success = system(cmd)
         puts '❌ Failed to retrieve RuboCop cop documentation' unless success
       end

data/specs/data/default-manifest.yml

@@ -1,12 +1,7 @@
 source:
   repo: DocOps/lab
   ref: v1
-  root: gems/docopslab-dev/assets/config-packs
-
 docs:
-  - source: docs/agent/AGENTS.md
-    target: AGENTS.md
-    synced: false
   - source: docs/agent/skills/*.md
     target: .agent/docs/skills/
     synced: true
@@ -17,6 +12,15 @@ docs:
     target: .agent/docs/roles/
     synced: true
 
+templates:
+  manifest:
+    - source: templates/AGENTS.markdown
+      target: ./AGENTS.md
+    - source: templates/gitignore
+      target: .gitignore
+    - source: templates/README.asciidoc
+      target: README.adoc
+
 tools:
   - tool: rubocop
     files:
@@ -62,3 +66,9 @@ tools:
       - source: actionlint/project.yml
         target: .config/actionlint.yml
         synced: false
+
+library:
+  enabled: true
+  source:
+    repo: DocOps/lab
+    ref: labdev-library

data/specs/data/library-index.yml

@@ -0,0 +1,22 @@
+categories:
+  - dest: README.adoc
+    source: gems/docopslab-dev/docs/library-readme.adoc
+
+  - dest: config-packs
+    source: gems/docopslab-dev/assets/config-packs
+
+  - dest: hooks
+    source: gems/docopslab-dev/assets/hooks
+
+  - dest: scripts
+    source: gems/docopslab-dev/assets/scripts
+
+  - dest: templates
+    source: gems/docopslab-dev/assets/templates
+
+  - dest: docs/agent
+    source: gems/docopslab-dev/docs/agent
+    prebuild: gemdo:gen_agent_docs
+  
+  - dest: templates/AGENTS.markdown
+    source: _docs/templates/AGENTS.markdown

data/specs/data/manifest-schema.yaml

@@ -5,7 +5,7 @@ $schema:
     version: v1
   properties:
     _meta:
-      req: [source,tools]
+      req: [source,tools,docs,library,attributes,templates]
     source:
       type: Map
       properties:
@@ -26,7 +26,7 @@ $schema:
           default: config-packs
     tools:
       type: ArrayTable
-      desc: List of config targets to sync & tools to permit.
+      desc: Registry of config targets to sync & tools to permit.
       properties:
         _meta:
           req: [tool,files]
@@ -43,7 +43,7 @@ $schema:
           default: false
         files:
           type: ArrayTable
-          desc: List of upstream/local file pairs
+          desc: Manifest of upstream/local file pairs
           properties:
             _meta:
               req: [upstream,local]
@@ -60,4 +60,142 @@ $schema:
             enabled:
               type: Boolean
               desc: Whether this file mapping is active
-              default: true
+              default: true
+          paths:
+            desc: Additional path-based config for tools that support it
+            type: Map
+            properties:
+              lint:
+                type: ArrayList
+                desc: List of paths to include in linting (relative to project root)
+              skip:
+                type: ArrayList
+                desc: List of paths to exclude from linting (relative to project root)
+              exts:
+                type: ArrayList
+                desc: |
+                  List of file extensions to include in linting (ex: ['adoc', 'md'])
+    docs:
+      type: ArrayTable
+      desc: Registry of documentation targets to sync.
+      properties:
+        _meta:
+          req: [source,target]
+        source:
+          type: Path
+          desc: Upstream path, relative to the library source path (usually `library/`) (supports globs)
+        target:
+          type: Path
+          desc: Local destination path within the project repo (directory if source is glob)
+        synced:
+          type: Boolean
+          desc: |
+            Whether to auto-sync this file from upstream.
+            WARNING: This overwrites local changes.
+          default: true
+    templates:
+      type: ArrayTable
+      desc: Registry of templates used to sync local file content.
+      properties:
+        _meta:
+          req: [source,target]
+        source:
+          type: Path
+          desc: Upstream path to a template file, relative to the library source path (usually `library/`).
+          docs: |
+            The base path for this value is established by the `library.source.path` property.
+        target:
+          type: Path
+          desc: |
+            Local destination path within the project repo, including filename and extension.
+        synced:
+          type: Boolean
+          desc: |
+            Whether to auto-sync this file from upstream.
+            If properly conigured, local modifications outside canonical blocks.
+          default: true
+        data:
+          type: Map
+          desc: Optional data to render the template with.
+
+    library:
+      type: Map
+      desc: |
+        Configuration for remote library fetch and host-wide cache.
+        This feature is for using an alternate library on a per-repo basis.
+        It can be used to cache and use non-standard libraries stored in a distinct path on the host.
+      properties:
+        _meta:
+          acc: [enabled,source,sync,catalog]
+        enabled:
+          type: Boolean
+          desc: Whether library sync operations are active.
+          default: true
+        source:
+          type: Map
+          desc: Remote source configuration for the library.
+          properties:
+            _meta:
+              req: [repo,ref]
+            type:
+              type: Slug
+              desc: Fetch strategy (git-branch | git-repo | http-archive)
+              default: git-branch
+            repo:
+              type: String
+              desc: |
+                Git repository to fetch library from, either on Git (`owner/name`) or a local path on host (value starting: `~` for relative to home, `.` for relevant to present directory, or `/` for asbolute paths).
+              default: DocOps/lab
+            ref:
+              type: String
+              desc: Branch or tag to fetch from.
+              default: labdev-library
+            path:
+              type: Path
+              desc: Path within the repository to the library root. Defaults to the branch root if omitted.
+        sync:
+          type: Map
+          desc: Caching and sync behaviour.
+          properties:
+            _meta:
+              req: []
+            mode:
+              type: Slug
+              desc: Fetch mode. Currently only latest-only is supported.
+              default: latest-only
+            cache_root:
+              type: Path
+              desc: |
+                Override the XDG-derived cache root for the library snapshot.
+                Defaults the the host's `$XDG_CACHE_HOME/docopslab/dev/library` (usually `~/.cache/docopslab/dev/library`).
+
+            local_path:
+              type: Path
+              desc: |
+                Local directory pointing to the active library snapshot (e.g. `library/current`).
+                When set and the catalog is present, this acts as the primary cache source and
+                the remote SHA check is skipped entirely; intended for the library maintainer's
+                own repo (monorepo use). Its parent directory is used as the effective cache root.
+                Downstream consumer projects omit this and rely on the XDG cache or `sync.cache_root`.
+        catalog:
+          type: Map
+          desc: Optional asset-level overrides; replaces any external library index file.
+          properties:
+            _meta:
+            overrides:
+              type: ArrayTable
+              desc: Per-asset path override entries applied after cache resolution.
+              properties:
+                _meta:
+                  req: [path]
+                path:
+                  type: Path
+                  desc: |
+                    Relative path within the library (ex: templates/README.asciidoc).
+                category:
+                  type: Slug
+                  desc: Override the inferred category label for this asset.
+                exclude:
+                  type: Boolean
+                  desc: Exclude this path from resolution results.
+                  default: false