docopslab-dev 0.1.0 → 0.3.0

data/lib/docopslab/dev.rb

@@ -8,16 +8,23 @@ require 'pathname'
 require 'shellwords'
 require_relative 'dev/version' # includes RUBY_TARGET
 require_relative 'dev/paths'
+require_relative 'dev/docker_aware'
+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 +44,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 +119,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
@@ -160,7 +196,7 @@ module DocOpsLab
       end
 
       def bootstrap_project
-        Initializer.bootstrap_project
+        Initializer.bootstrap_project(self)
       end
 
       def install_vale_styles
@@ -205,6 +241,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 +357,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 +398,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 +417,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:
@@ -35,6 +39,14 @@ tools:
       - source: vale/project.ini
         target: .config/vale.local.ini
         synced: false
+    paths:
+      lint: ['.']
+      skip:
+        - build/*
+        - specs/*
+        - .agent/**/*
+        - .config/.vendor/**/*
+      exts: ['adoc']
 
   - tool: htmlproofer
     enabled: false  # Disabled by default, enable per project
@@ -62,3 +74,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

data/specs/data/tasks-def.yml

@@ -18,15 +18,16 @@ labdev:
     _desc: Run assessments on the project environment and managed assets
     env:
       _desc: Assess the local environment and configuration
-    updates:
-      _desc: Check for updates to managed assets from upstream
     all:
       _alias: "labdev:check"
   init:
+    _desc: Initialize development environment assets for this project
     all:
       _desc: Bootstrap the development environment for this project
     docs:
       _desc: Sync agent documentation files to project
+    templates:
+      _desc: Bootstrap cast targets from prime templates (init-only; skips existing files)
   run: 
     # there is no labdev:run:all
     script:
@@ -87,15 +88,19 @@ labdev:
     shellcheck:
       _desc: Run the base shellcheck command and options.
       _args:
+        path:
+          summ: Optional path to a specific file, directory, or glob to check.
+          required: false
         opts:
           summ: Additional arguments to pass to the shellcheck command.
           docs: |
             Use like:
-             bundle exec rake 'labdev:run:shellcheck["--enable=all --format=gcc"]'
+             bundle exec rake 'labdev:run:shellcheck[scripts/build.sh,"--enable=all --format=gcc"]'
           required: false
       _test:
         - bundle exec rake 'labdev:run:shellcheck'
-        - bundle exec rake 'labdev:run:shellcheck["--enable=all --format=gcc"]'
+        - bundle exec rake 'labdev:run:shellcheck[scripts/build.sh]'
+        - bundle exec rake 'labdev:run:shellcheck[scripts/,"--enable=all --format=gcc"]'
     actionlint:
       _desc: Run the base actionlint command and options.
       _args:
@@ -111,16 +116,26 @@ labdev:
   sync:
     _desc: Sync all managed files (configs, scripts, docs, styles, etc)
     all:
-      _alias: "labdev:sync"
+      _desc: Check library freshness then sync all managed assets (configs, scripts, docs, templates, hooks, styles)
     configs:
       _desc: Sync configuration files from config pack
     scripts:
       _desc: Update non-local (`.vendor/`) scripts from upstream
     docs:
       _desc: Sync files to untracked local paths
-      # _args:
-      #   force:
-      # GET RID OF docs[force], this makes no sense, we always overwrite
+    templates:
+      _desc: Sync canonical blocks from prime templates into manifest cast targets
+      _args:
+        path:
+          summ: Optional target file path to restrict the sync to a single entry.
+          required: false
+        dry:
+          summ: Pass 'dry' to preview changes without writing files.
+          required: false
+      _test:
+        - bundle exec rake labdev:sync:templates
+        - bundle exec rake 'labdev:sync:templates[AGENTS.md]'
+        - bundle exec rake 'labdev:sync:templates[AGENTS.md,dry]'
     styles:
       _desc: Sync Vale styles from gem source to project
       local:
@@ -129,6 +144,22 @@ labdev:
         _desc: Sync custom styles from gem and download remote packages
     hooks:
       _desc: Update git hooks from templates (interactive)
+    library:
+      _desc: Fetch the remote library (if stale) and sync content to manifest-configured paths
+      _test:
+        - bundle exec rake labdev:sync:library
+      stage:
+        _desc: Stage a local library directory into the cache and sync to project paths (bypasses remote fetch)
+        _args:
+          path:
+            summ: |
+              Optional path to the local library directory to stage.
+              Defaults to manifest library.local_path, then .library/ in the
+              current directory, then ../lab/.library/ for downstream projects.
+            required: false
+        _test:
+          - bundle exec rake labdev:sync:library:stage
+          - bundle exec rake 'labdev:sync:library:stage[../lab/.library]'
     vale:
       _desc: Sync Vale config and all styles (custom + remote packages)
       local:
@@ -286,9 +317,13 @@ labdev:
           required: false
   show:
     scripts:
-      _desc: List available script templatest
+      _desc: List available script templates
     hooks:
       _desc: List available hook templates
+    library:
+      _desc: Show the current library cache status and version
+      _test:
+        - bundle exec rake labdev:show:library
     rule:
       _desc: Show details about a specific linting rule
       _args:
@@ -301,13 +336,90 @@ labdev:
       _test:
         - bundle exec rake 'labdev:show:rule[rubocop,Layout/LineLength]'
         - bundle exec rake 'labdev:show:rule[vale,DocOpsLab-Authoring.ExNotEg]'
+  skim:
+    _desc: Skim source files for machine-oriented structured outlines (AsciiDoc + Markdown autodetect)
+    _args:
+      path:
+        summ: |
+          File path, directory, or glob of source files.
+          Format auto-detected from extension.
+        required: true
+      form:
+        summ: |
+          Output shape: tree, flat, or tree,flat (comma-separated).
+          Defaults to tree for AsciiDoc, flat for Markdown.
+          When form is explicitly passed, output defaults to JSON.
+        required: false
+      syntax:
+        summ: |
+          Override output format: json or yaml.
+          Default: yaml when form is omitted; json when form is explicitly passed.
+        required: false
+    _test:
+      - bundle exec rake 'labdev:skim[README.adoc]'
+      - bundle exec rake 'labdev:skim[.,flat]'
+      - bundle exec rake 'labdev:skim[.,tree]'
+      - bundle exec rake 'labdev:skim[*.adoc,,json]'
+      - bundle exec rake 'labdev:skim[.,both]'
+    adoc:
+      _desc: Skim AsciiDoc source files using Sourcerer::SourceSkim
+      _args:
+        path:
+          summ: File path, directory, or glob of AsciiDoc source files.
+          required: true
+        form:
+          summ: |
+            Output shape: tree, flat, or tree,flat (comma-separated).
+            Defaults to tree. When form is explicitly passed, output defaults to JSON.
+          required: false
+        syntax:
+          summ: |
+            Override output format: json or yaml.
+            Default: yaml when form is omitted; json when form is explicitly passed.
+          required: false
+      _test:
+        - bundle exec rake 'labdev:skim:adoc[README.adoc]'
+        - bundle exec rake 'labdev:skim:adoc[.,flat]'
+        - bundle exec rake 'labdev:skim:adoc[*.adoc,,yaml]'
+    md:
+      _desc: Skim Markdown source files using Sourcerer::SourceSkim. Supports upstream:local overlay path syntax.
+      _docs: |
+        Accepts a single path or an upstream:local overlay pair (colon-separated).
+
+        With two paths, local files shadow upstream files sharing the same relative path,
+        and local-only files are appended. This is useful when a project maintains local
+        additions or overrides alongside a synced upstream docs library.
+
+        Examples:
+          Single path:   .agent/docs/
+          Overlay pair:  .agent/docs/:_docs/agent/
+      _args:
+        path:
+          summ: |
+            File path, directory, or glob of Markdown source files.
+            Optionally provide two directories as upstream:local to merge with local overrides taking precedence.
+          required: true
+        form:
+          summ: |
+            Output shape: tree, flat, or tree,flat (comma-separated).
+            Defaults to flat for Markdown. When form is explicitly passed, output defaults to JSON.
+          required: false
+        syntax:
+          summ: |
+            Override output format: json or yaml.
+            Default: yaml when form is omitted; json when form is explicitly passed.
+          required: false
+      _test:
+        - bundle exec rake 'labdev:skim:md[.agent/docs/]'
+        - bundle exec rake 'labdev:skim:md[.agent/docs/,flat,json]'
+        - bundle exec rake 'labdev:skim:md[.agent/docs/:_docs/agent/,flat,json]'
   # ADDING:
   help:
     _desc: Show help information about labdev tasks
     _docs: |
       Default behavior is to show general help information.
 
-      Use like:
+      Use like: 
        bundle exec rake 'labdev:help[lint:ruby]'
     _args:
       task_string: