docopslab-dev 0.1.0 → 0.2.0

data/lib/docopslab/dev/library/cache.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'digest'
+require_relative '../../dev'
+
+module DocOpsLab
+  module Dev
+    module Library
+      # Manages the host-wide library cache at ~/.cache/docopslab/dev/library/.
+      #
+      # Cache layout:
+      #   current/    Active library used for sync and resolve operations.
+      #   previous/   Previous snapshot retained for fast rollback.
+      #
+      # The XDG_CACHE_HOME env variable is respected; defaults to ~/.cache.
+      module Cache
+        class << self
+          # Optional path override; set by Library.sync!/fetch! when manifest
+          # specifies `library.sync.cache_root`. Cleared after the operation.
+          attr_writer :root_override
+
+          # Absolute path to the cache root (~/.cache/docopslab/dev/library/).
+          # Respects +root_override+ if set, then $XDG_CACHE_HOME, then ~/.cache.
+          def root
+            return File.expand_path(@root_override) if @root_override
+
+            base = ENV.fetch('XDG_CACHE_HOME', File.join(Dir.home, '.cache'))
+            File.join(base, Dev.xdg_cache_subpath)
+          end
+
+          # Temporarily override the cache root for the duration of a block.
+          # Restores the previous value even if the block raises.
+          def with_root_override path
+            previous = @root_override
+            @root_override = path
+            yield
+          ensure
+            @root_override = previous
+          end
+
+          # Absolute path to the current library snapshot.
+          def current_path
+            File.join(root, 'current')
+          end
+
+          # Absolute path to the previous library snapshot (rollback target).
+          def previous_path
+            File.join(root, 'previous')
+          end
+
+          # Absolute path to the catalog inside the current snapshot.
+          def catalog_path
+            File.join(current_path, 'catalog.json')
+          end
+
+          # Load and return the parsed catalog from the current snapshot.
+          # Returns nil if no cache is present or the catalog is unreadable.
+          def catalog
+            return nil unless File.exist?(catalog_path)
+
+            load_catalog_json(catalog_path)
+          end
+
+          # True if a current snapshot with a readable catalog is present.
+          def available?
+            File.exist?(catalog_path)
+          end
+
+          # The remote HEAD SHA stored from the last successful fetch, or nil.
+          def stored_head
+            return nil unless File.exist?(head_path)
+
+            s = File.read(head_path).strip
+            s.empty? ? nil : s
+          rescue StandardError
+            nil
+          end
+
+          # Persist the remote HEAD SHA alongside the cache.
+          def write_head! sha
+            FileUtils.mkdir_p(root)
+            File.write(head_path, sha.to_s.strip)
+          end
+
+          # True if the cache exists and was generated within +max_age_hours+.
+          def fresh? max_age_hours=24
+            return false unless available?
+
+            ts = catalog&.dig('generated_at')
+            return false unless ts
+
+            (Time.now.utc - Time.parse(ts)) < max_age_hours * 3600
+          rescue ArgumentError
+            false
+          end
+
+          # Rotate current/ to previous/, removing any prior previous/ snapshot.
+          # Returns true if a rotation was performed, false if current/ was absent.
+          def rotate!
+            return false unless Dir.exist?(current_path)
+
+            FileUtils.rm_rf(previous_path)
+            FileUtils.mv(current_path, previous_path)
+            true
+          end
+
+          # Install a directory as the new current/ snapshot.
+          # Rotates any existing current/ to previous/ first.
+          # source_dir must be an existing directory.
+          def write! source_dir
+            raise ArgumentError, "Source directory not found: #{source_dir}" unless Dir.exist?(source_dir)
+
+            rotate! if Dir.exist?(current_path)
+            FileUtils.mkdir_p(File.dirname(current_path))
+            FileUtils.cp_r(source_dir, current_path)
+            true
+          end
+
+          # Swap previous/ back to current/.
+          # Returns false if no previous/ snapshot exists.
+          def rollback!
+            return false unless Dir.exist?(previous_path)
+
+            FileUtils.rm_rf(current_path)
+            FileUtils.mv(previous_path, current_path)
+            true
+          end
+
+          # Return a status hash describing the current snapshot.
+          def status
+            if available?
+              meta = catalog
+              {
+                available: true,
+                version: meta&.dig('library_version'),
+                ref: meta&.dig('library_ref'),
+                generated_at: meta&.dig('generated_at'),
+                cache_path: current_path,
+                has_previous: Dir.exist?(previous_path)
+              }
+            else
+              { available: false, cache_path: current_path }
+            end
+          end
+
+          CATALOG_JSON_KEYS = %w[library_version library_ref generated_at files].freeze
+
+          private
+
+          def head_path
+            File.join(root, 'remote_head')
+          end
+
+          # Parse catalog.json, returning the hash or nil on any error.
+          def load_catalog_json path
+            data = JSON.parse(File.read(path))
+            CATALOG_JSON_KEYS.all? { |k| data.key?(k) } ? data : nil
+          rescue JSON::ParserError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/library/fetch.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'shellwords'
+require 'tmpdir'
+require 'zlib'
+
+module DocOpsLab
+  module Dev
+    module Library
+      # Fetches the remote asset library and installs it to the host cache.
+      #
+      # Fetch strategy (in order of preference):
+      #   1. `gh` CLI downloads the branch via the GitHub API tarball endpoint.
+      #   2. `git clone --depth=1` with sparse checkout; pulls only the library
+      #      sub-tree from the remote branch.
+      #
+      # Auth notes:
+      #   DocOps/lab is a public repository; no credentials are required.
+      #   A GITHUB_TOKEN env variable can be added in a future iteration if
+      #   private repo support is needed.
+      module Fetch
+        class << self
+          # Fetch the remote library and install it to the host cache.
+          #
+          # config is a hash (or nil) mirroring the `library.source` manifest
+          # block:
+          #   { 'repo' => '...', 'branch' => '...', 'path' => '...' }
+          #
+          # Returns true on success, false on failure (logs a warning).
+          def call config={}
+            source = resolve_source(config)
+
+            Dir.mktmpdir('docopslab-library-') do |tmpdir|
+              dest = File.join(tmpdir, 'library')
+              FileUtils.mkdir_p(dest)
+
+              ok = fetch_git_content(source[:repo], source[:branch], source[:path], dest)
+              unless ok
+                warn '⚠️  Library fetch failed; cache not updated.'
+                return false
+              end
+
+              sha = remote_head_for_source(source)
+              Cache.write!(dest)
+              Cache.write_head!(sha) if sha
+              puts "✅ Library fetched and cached at #{Cache.current_path}"
+              true
+            end
+          rescue StandardError => e
+            warn "⚠️  Library fetch error: #{e.message}"
+            false
+          end
+
+          # True if the `gh` CLI is present and executable.
+          def gh_available?
+            system('gh --version > /dev/null 2>&1')
+          end
+
+          # True if the `git` CLI is present and executable.
+          def git_available?
+            system('git --version > /dev/null 2>&1')
+          end
+
+          # Look up the current HEAD SHA for the configured remote branch.
+          # Runs `git ls-remote` (requires git and network access.)
+          # Returns the SHA string, or nil on failure.
+          def remote_head config={}
+            remote_head_for_source(resolve_source(config))
+          end
+
+          private
+
+          def remote_head_for_source source
+            url = "https://github.com/#{source[:repo]}.git"
+            ref = "refs/heads/#{source[:branch]}"
+            out = `git ls-remote #{Shellwords.escape(url)} #{Shellwords.escape(ref)} 2>/dev/null`
+            sha = out.split("\t").first&.strip
+            sha&.empty? ? nil : sha
+          rescue StandardError
+            nil
+          end
+
+          def resolve_source config
+            src = config.is_a?(Hash) ? (config['source'] || config[:source] || {}) : {}
+            raw = src['path'] || src[:path]
+            {
+              repo:   src['repo']   || src[:repo]   || Dev.default_library_repo,
+              branch: src['branch'] || src[:branch] || Dev.default_library_branch,
+              path:   raw&.to_s&.delete_suffix('/')
+            }
+          end
+
+          # Route to the best available CLI tool.
+          # Prefer git clone (simpler, transparent, no extraction layer).
+          # Fall back to gh tarball download if git is unavailable.
+          def fetch_git_content repo, branch, path, dest
+            if git_available?
+              fetch_via_git_clone(repo, branch, path, dest)
+            elsif gh_available?
+              fetch_via_gh(repo, branch, path, dest)
+            else
+              warn '⚠️  Neither `git` nor `gh` CLI is available. Cannot fetch library.'
+              false
+            end
+          end
+
+          # Use `gh api` to download the branch tarball, then extract the
+          # library sub-path.
+          def fetch_via_gh repo, branch, path, dest
+            owner, repo_name = repo.split('/', 2)
+            Dir.mktmpdir('docopslab-gh-') do |tmpdir|
+              archive = File.join(tmpdir, 'library.tar.gz')
+              cmd = "gh api repos/#{Shellwords.escape(owner)}/#{Shellwords.escape(repo_name)}" \
+                    "/tarball/#{Shellwords.escape(branch)} " \
+                    "> #{Shellwords.escape(archive)}"
+              unless system(cmd)
+                warn '⚠️  `gh api` call failed.'
+                return false
+              end
+              extract_subpath_from_tarball(archive, path, dest)
+            end
+          end
+
+          # Use `git clone --depth=1` to pull the library branch.
+          # If +path+ is given, only that subdirectory is checked out (sparse);
+          # otherwise the entire branch root is copied.
+          def fetch_via_git_clone repo, branch, path, dest
+            Dir.mktmpdir('docopslab-git-') do |tmpdir|
+              clone_dir = File.join(tmpdir, 'clone')
+              url = "https://github.com/#{repo}.git"
+              clone_flags = path ? '--filter=blob:none --sparse' : ''
+              clone_cmd = [
+                'git clone',
+                '--depth=1',
+                "--branch #{Shellwords.escape(branch)}",
+                clone_flags,
+                Shellwords.escape(url),
+                Shellwords.escape(clone_dir)
+              ].reject(&:empty?).join(' ')
+
+              unless system(clone_cmd)
+                warn '⚠️  `git clone` failed.'
+                return false
+              end
+
+              if path
+                sparse_cmd = "git -C #{Shellwords.escape(clone_dir)} sparse-checkout set #{Shellwords.escape(path)}"
+                system(sparse_cmd)
+              end
+
+              source_path = path ? File.join(clone_dir, path) : clone_dir
+              unless Dir.exist?(source_path)
+                warn "⚠️  Library path '#{path}' not found in remote branch."
+                return false
+              end
+
+              FileUtils.cp_r("#{source_path}/.", dest)
+              true
+            end
+          end
+
+          # Extract all entries under `path/` from a GitHub-format tarball.
+          # GitHub tarballs wrap everything in a top-level `owner-repo-SHA/`
+          # prefix directory; this method strips that prefix automatically.
+          def extract_subpath_from_tarball archive, path, dest
+            require 'rubygems/package'
+
+            Dir.mktmpdir('docopslab-tar-') do |extract_dir|
+              Zlib::GzipReader.open(archive) do |gz|
+                Gem::Package::TarReader.new(gz) do |tar|
+                  tar.each do |entry|
+                    parts = entry.full_name.split('/', 2)
+                    next if parts.length < 2
+
+                    relative = parts[1]
+                    next if relative.empty?
+
+                    if path
+                      next unless relative.start_with?("#{path}/") || relative == path
+
+                      local_relative = relative.delete_prefix("#{path}/")
+                    else
+                      local_relative = relative
+                    end
+                    target = File.join(extract_dir, local_relative)
+
+                    if entry.directory?
+                      FileUtils.mkdir_p(target)
+                    elsif entry.file?
+                      FileUtils.mkdir_p(File.dirname(target))
+                      File.binwrite(target, entry.read)
+                    end
+                  end
+                end
+              end
+
+              FileUtils.cp_r("#{extract_dir}/.", dest)
+            end
+            true
+          rescue StandardError => e
+            warn "⚠️  Tarball extraction failed: #{e.message}"
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/library.rb

@@ -0,0 +1,328 @@
+# 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/.
+    # 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)
+          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