docopslab-dev 0.1.0 → 0.3.0

data/lib/docopslab/dev/initializer.rb

@@ -14,7 +14,7 @@ module DocOpsLab
           FileUtils.mkdir_p('.config')
 
           # Copy template from gem
-          FileUtils.cp(MANIFEST_DEF_PATH, MANIFEST_PATH)
+          FileUtils.cp(Dev.manifest_def_path, MANIFEST_PATH)
           puts "✅ Created #{MANIFEST_PATH}"
         end
 
@@ -24,7 +24,10 @@ module DocOpsLab
             return false
           end
 
-          FileUtils.cp(GITIGNORE_STUB_SOURCE_PATH, '.gitignore')
+          Library.ensure_available!
+          stub = Library.resolve('templates/gitignore') ||
+                 raise('Library templates/gitignore not found; run `labdev:sync:library`.')
+          FileUtils.cp(stub, '.gitignore')
           puts '✅ Created .gitignore file'
           true
         end
@@ -35,7 +38,10 @@ module DocOpsLab
             return false
           end
 
-          FileUtils.cp(GEMFILE_STUB_SOURCE_PATH, 'Gemfile')
+          Library.ensure_available!
+          stub = Library.resolve('templates/Gemfile') ||
+                 raise('Library templates/Gemfile not found; run `labdev:sync:library`.')
+          FileUtils.cp(stub, 'Gemfile')
           puts '✅ Created Gemfile'
           true
         end
@@ -46,7 +52,10 @@ module DocOpsLab
             return false
           end
 
-          FileUtils.cp(RAKEFILE_STUB_SOURCE_PATH, 'Rakefile')
+          Library.ensure_available!
+          stub = Library.resolve('templates/Rakefile') ||
+                 raise('Library templates/Rakefile not found; run `labdev:sync:library`.')
+          FileUtils.cp(stub, 'Rakefile')
           puts '✅ Created Rakefile'
           true
         end
@@ -62,8 +71,8 @@ module DocOpsLab
           true
         end
 
-        def bootstrap_project
-          puts '� Bootstrapping DocOps Lab project...'
+        def bootstrap_project context = nil
+          puts '🚀 Bootstrapping DocOps Lab project...'
           puts ''
 
           created = []
@@ -81,13 +90,27 @@ module DocOpsLab
           puts ''
           if created.any?
             puts "✅ Bootstrap complete! Created: #{created.join(', ')}"
-            puts ''
-            puts 'Next steps:'
-            puts '  1. bundle exec rake labdev:sync:all  # or: docker run ... labdev:sync:all'
-            puts '  2. Start using labdev tasks!'
           else
-            puts '✅ Project already initialized, nothing to create'
+            puts '✅ Bootstrap files already exist'
           end
+
+          # Initialize templates from manifest (if context provided, use it; else use Dev context)
+          context ||= Dev
+          puts ''
+          puts '🎨 Initializing templates from manifest...'
+          template_results = CastOps.init_cast_targets(context)
+
+          if template_results.any?
+            puts "✅ Initialized #{template_results.size} template(s)"
+          else
+            puts '✅ Templates already initialized'
+          end
+
+          puts ''
+          puts 'Next steps:'
+          puts '  1. bundle exec rake labdev:sync:all  # or: docker run ... labdev:sync:all'
+          puts '  2. Review and customize the generated files'
+          puts '  3. Start using labdev tasks: bundle exec rake labdev:check:env'
         end
       end
     end

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