Kobold 0.3.4 → 0.4.0

data/lib/Kobold/config.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+
+module Kobold
+  # Reads, writes, validates, and generates .kobold TOML configuration files.
+  class Config
+    REQUIRED_KEYS = %w[repo source].freeze
+    OPTIONAL_KEYS = %w[dir branch commit label].freeze
+    ALL_DEP_KEYS = (REQUIRED_KEYS + OPTIONAL_KEYS).freeze
+
+    attr_reader :format_version, :includes, :dependencies, :path
+
+    def self.read(path)
+      full_path = File.expand_path(path)
+      raise Errors::ConfigError, "Config file not found: #{full_path}" unless File.file?(full_path)
+
+      new(data: TomlRB.load_file(full_path), path: full_path)
+    end
+
+    def self.write(path, config)
+      File.write(path, TomlRB.dump(config.to_h))
+    end
+
+    def self.generate(dependencies: [], includes: [])
+      data = build_base_data(includes)
+      dependencies.each { |dep| add_dep_to_data(data, dep) }
+      new(data: data)
+    end
+
+    def self.validate(data)
+      validate_kobold_section(data)
+      validate_includes(data["kobold"])
+      validate_dependencies(data["dependencies"])
+      true
+    end
+
+    def initialize(data:, path: nil)
+      self.class.validate(data)
+      @path = path
+      kobold = data["kobold"]
+      @format_version = kobold["format_version"]
+      @includes = kobold.fetch("includes", [])
+      @dependencies = data.fetch("dependencies", {})
+    end
+
+    def to_h
+      h = { "kobold" => { "format_version" => @format_version } }
+      h["kobold"]["includes"] = @includes unless @includes.empty?
+      h["dependencies"] = @dependencies unless @dependencies.empty?
+      h
+    end
+
+    def each_dependency(&block)
+      @dependencies.each(&block)
+    end
+
+    def add_dependency(name, dep)
+      @dependencies[name] = dep.each_with_object({}) { |(k, v), h| h[k.to_s] = v unless v.nil? }
+    end
+
+    def remove_dependency(name)
+      @dependencies.delete(name)
+    end
+
+    def dependency?(name)
+      @dependencies.key?(name)
+    end
+
+    def dependency(name)
+      @dependencies[name]
+    end
+
+    def update_dependency(name, key, value)
+      raise Errors::DependencyNotFound, name unless @dependencies.key?(name)
+
+      value.nil? ? @dependencies[name].delete(key.to_s) : @dependencies[name][key.to_s] = value
+    end
+
+    def self.build_base_data(includes)
+      data = { "kobold" => { "format_version" => Kobold::FORMAT_VERSION }, "dependencies" => {} }
+      data["kobold"]["includes"] = includes unless includes.empty?
+      data
+    end
+    private_class_method :build_base_data
+
+    def self.add_dep_to_data(data, dep)
+      dep = dep.dup
+      name = dep.delete(:name) || dep.delete("name")
+      raise Errors::ConfigError, "Dependency must have a 'name' key" unless name
+
+      entry = {}
+      dep.each { |k, v| entry[k.to_s] = v }
+      data["dependencies"][name] = entry
+    end
+    private_class_method :add_dep_to_data
+
+    def self.validate_kobold_section(data)
+      kobold = data["kobold"]
+      raise Errors::ConfigError, "Missing [kobold] section" unless kobold.is_a?(Hash)
+
+      version = kobold["format_version"]
+      raise Errors::ConfigError, "Missing format_version in [kobold] section" unless version
+      raise Errors::InvalidFormat.new(version, Kobold::FORMAT_VERSION) unless version == Kobold::FORMAT_VERSION
+    end
+    private_class_method :validate_kobold_section
+
+    def self.validate_includes(kobold)
+      return unless kobold.key?("includes")
+      return if kobold["includes"].is_a?(Array) && kobold["includes"].all? { |i| i.is_a?(String) }
+
+      raise Errors::ConfigError, "'includes' must be an array of strings"
+    end
+    private_class_method :validate_includes
+
+    def self.validate_dependencies(deps)
+      return unless deps.is_a?(Hash)
+
+      deps.each { |name, dep| validate_single_dep(name, dep) }
+    end
+    private_class_method :validate_dependencies
+
+    def self.validate_single_dep(name, dep)
+      raise Errors::ConfigError, "Dependency '#{name}' must be a table" unless dep.is_a?(Hash)
+
+      REQUIRED_KEYS.each do |key|
+        raise Errors::ConfigError, "Dependency '#{name}' is missing required key '#{key}'" unless dep.key?(key)
+      end
+
+      unknown = dep.keys - ALL_DEP_KEYS
+      raise Errors::ConfigError, "Dependency '#{name}' has unknown keys: #{unknown.join(", ")}" unless unknown.empty?
+      raise Errors::ConfigError, "Dependency '#{name}' has a label but no commit" if dep["label"] && !dep["commit"]
+    end
+    private_class_method :validate_single_dep
+  end
+end

data/lib/Kobold/database.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+require "fileutils"
+
+module Kobold
+  # Manages a single named database (cache directory).
+  #
+  # Each database lives at:
+  #   <KOBOLD_DIR>/databases/<name>/
+  #
+  # Contains a registry.toml tracking registered repos and a repos/ directory
+  # holding cached bare clones and worktrees.
+  class Database
+    # List all databases that exist on disk.
+    #
+    # @return [Array<String>] database names
+    def self.list_databases
+      databases_dir = File.join(Kobold::KOBOLD_DIR, "databases")
+      return [] unless Dir.exist?(databases_dir)
+
+      Dir.children(databases_dir)
+         .select { |name| File.directory?(File.join(databases_dir, name)) }
+         .sort
+    end
+
+    # Check if a named database exists on disk.
+    #
+    # @param name [String] database name
+    # @return [Boolean]
+    def self.exists?(name)
+      Dir.exist?(File.join(Kobold::KOBOLD_DIR, "databases", name))
+    end
+
+    REGISTRY_FILE = "registry.toml"
+
+    attr_reader :name
+
+    # @param name [String] the database name (default: "default")
+    def initialize(name = "default")
+      @name = name
+    end
+
+    # Absolute path to this database directory.
+    #
+    # @return [String]
+    def path
+      File.join(Kobold::KOBOLD_DIR, "databases", @name)
+    end
+
+    # Ensure the database directory and registry exist.
+    #
+    # @return [void]
+    def setup
+      FileUtils.mkdir_p(repos_dir)
+      write_registry({}) unless File.file?(registry_path)
+    end
+
+    # Check if this database exists on disk.
+    #
+    # @return [Boolean]
+    def exists?
+      Dir.exist?(path)
+    end
+
+    # Delete this entire database and all its contents.
+    #
+    # @return [void]
+    def delete
+      raise Errors::DatabaseNotFound, @name unless exists?
+
+      FileUtils.rm_rf(path)
+    end
+
+    # Register a repo in this database.
+    #
+    # @param slug [String] the repo slug (e.g. "raysan5-raylib")
+    # @param source_url [String] the full clone URL
+    # @return [Hash] the registered entry
+    def register_repo(slug, source_url)
+      with_locked_registry do |reg|
+        reg[slug] = { "source_url" => source_url }
+        reg[slug]
+      end
+    end
+
+    # Unregister a repo from this database.
+    #
+    # @param slug [String] the repo slug
+    # @return [void]
+    def unregister_repo(slug)
+      with_locked_registry do |reg|
+        raise Errors::RepoNotFound, slug unless reg.key?(slug)
+
+        reg.delete(slug)
+      end
+    end
+
+    # List all registered repos.
+    #
+    # @return [Hash] slug => { "source_url" => "..." }
+    def list_repos
+      registry
+    end
+
+    # Get a Repo object for a registered slug.
+    #
+    # @param slug [String] the repo slug
+    # @return [Kobold::Repo]
+    def repo(slug)
+      reg = registry
+      raise Errors::RepoNotFound, slug unless reg.key?(slug)
+
+      Repo.new(self, slug, reg[slug]["source_url"])
+    end
+
+    # Convert a "user/repo" string to a slug.
+    #
+    # @param repo_path [String] e.g. "raysan5/raylib"
+    # @return [String] e.g. "raysan5-raylib"
+    def self.slugify(repo_path)
+      repo_path.gsub("/", "-")
+    end
+
+    # Path to the repos/ subdirectory.
+    #
+    # @return [String]
+    def repos_dir
+      File.join(path, "repos")
+    end
+
+    private
+
+    def registry_path
+      File.join(path, REGISTRY_FILE)
+    end
+
+    def lock_path
+      File.join(path, "#{REGISTRY_FILE}.lock")
+    end
+
+    def registry
+      return {} unless File.file?(registry_path)
+
+      data = TomlRB.load_file(registry_path)
+      data.fetch("repos", {})
+    end
+
+    def write_registry(repos_hash)
+      FileUtils.mkdir_p(path)
+      data = { "repos" => repos_hash }
+      File.write(registry_path, TomlRB.dump(data))
+    end
+
+    # Acquire an exclusive file lock, read the registry, yield the
+    # mutable hash, then write it back.  Prevents TOCTOU races when
+    # multiple processes share a database.
+    def with_locked_registry
+      FileUtils.mkdir_p(path)
+      File.open(lock_path, File::CREAT | File::RDWR) do |lock|
+        lock.flock(File::LOCK_EX)
+        reg = registry
+        result = yield reg
+        write_registry(reg)
+        result
+      end
+    end
+  end
+end

data/lib/Kobold/errors.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Kobold
+  module Errors
+    class RepoNotFound < StandardError
+      def initialize(slug)
+        super("Repository not found: #{slug}")
+      end
+    end
+
+    class WorktreeExists < StandardError
+      def initialize(path)
+        super("Worktree already exists at: #{path}")
+      end
+    end
+
+    class ConfigError < StandardError; end
+
+    class DatabaseNotFound < StandardError
+      def initialize(name)
+        super("Database not found: #{name}")
+      end
+    end
+
+    class InvalidFormat < StandardError
+      def initialize(version, expected)
+        super("Invalid format version '#{version}', expected '#{expected}'")
+      end
+    end
+
+    class CloneError < StandardError
+      def initialize(url, message)
+        super("Failed to clone #{url}: #{message}")
+      end
+    end
+
+    class FetchError < StandardError
+      def initialize(slug, message)
+        super("Failed to fetch #{slug}: #{message}")
+      end
+    end
+
+    class GitError < StandardError; end
+
+    class DependencyNotFound < StandardError
+      def initialize(name)
+        super("Dependency not found: #{name}")
+      end
+    end
+
+    class DatabaseExists < StandardError
+      def initialize(name)
+        super("Database already exists: #{name}")
+      end
+    end
+
+    class LinkError < StandardError; end
+  end
+end

data/lib/Kobold/fetch.rb

@@ -1,62 +1,19 @@
 # frozen_string_literal: true
 
-require "tty-config"
-require 'fileutils'
-require 'git'
-
-#require_relative "Kobold/vars.rb"
-
 module Kobold
   class << self
-    def fetch
-      Kobold.first_time_setup if !File.directory? "#{KOBOLD_DIR}/repo_cache"
-      if !File.file? "#{Dir.pwd}/.kobold"
-        puts "ERROR: Kobold file not found at '#{Dir.pwd}'"
-        return
-      end
-      settings = Kobold.read_config(Dir.pwd)
-
-      if Kobold::FORMAT_VERSION == settings["_kobold_config"]["format_version"]
-        # iterate over all dependencies
-        settings.each do |key, value|
-          if key[0] == '_' 
-            next
-          end
-          repo_dir = "#{KOBOLD_DIR}/repo_cache/#{value['repo'].gsub('/', '-')}"
-
-          source_repo = nil;
-          # check if source exists
-          if !Dir.exist? "#{repo_dir}/source" # TODO: make this properly check for git repo
-            # if it doesnt, make it
-            FileUtils.mkdir_p "#{repo_dir}/source"
-            FileUtils.mkdir_p "#{repo_dir}/worktrees"
-            FileUtils.mkdir_p "#{repo_dir}/worktrees/branched"
-            FileUtils.mkdir_p "#{repo_dir}/worktrees/sha"
-            FileUtils.mkdir_p "#{repo_dir}/worktrees/labelled"
-            FileUtils.mkdir_p "#{repo_dir}/branches"
-            source_repo = clone_git_repo "#{value["source"]}/#{value['repo']}.git", "#{repo_dir}/source"
-            next
-            # TODO this may need to be reworked, might not fetch new branches that are required
-            # if they havent been invoked previously.
-            # works good enough for now :3
-          else
-            source_repo = Git.open("#{repo_dir}/source")
-          end
-
-          progress_bar = TTY::ProgressBar.new("[:bar] Fetching: #{value["source"]}/#{value['repo']}.git ", bar_format: :blade, total: nil, width: 45)
-
-          thread = Thread.new(abort_on_exception: true) do
-            source_repo.fetch(all: true)
-          end
-          progress_bar.start
-          while thread.status
-            progress_bar.advance
-            sleep 0.016
-          end
-          puts
-          #return thread.value
-        end
-      end
+    # Fetch updates for all repos referenced in a .kobold config.
+    #
+    # This is a convenience wrapper around Kobold::Manager#fetch_all.
+    #
+    # @param config_path [String] path to the .kobold file (default: current dir)
+    # @param database_name [String] which database to use (default: "default")
+    # @return [Array<Hash>] results for each dependency fetched
+    def fetch(config_path: Dir.pwd, database_name: "default")
+      manager = Manager.new(database: database_name)
+      results = manager.fetch_all(config_path: config_path)
+      puts "Fetch complete."
+      results
     end
   end
 end

data/lib/Kobold/git_ops.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "git"
+require "fileutils"
+require "open3"
+
+module Kobold
+  # Low-level Git operations used internally by Repo and other classes.
+  # All methods are module-level (stateless).
+  module GitOps
+    module_function
+
+    # Clone a repository as a bare clone.
+    #
+    # @param url [String] the Git remote URL
+    # @param path [String] the local destination path
+    # @return [Git::Base] the opened bare repository
+    def clone(url, path)
+      puts "Cloning: #{url}"
+      _out, err, status = Open3.capture3("git", "clone", "--bare", url, path)
+      raise Errors::CloneError.new(url, err) unless status.success?
+
+      puts "Clone complete."
+      Git.bare(path)
+    rescue Errors::CloneError
+      raise
+    rescue StandardError => e
+      raise Errors::CloneError.new(url, e.message)
+    end
+
+    # Open an existing Git repository (bare or non-bare).
+    #
+    # @param path [String] path to the repository
+    # @return [Git::Base]
+    def open(path)
+      if bare_repo?(path)
+        Git.bare(path)
+      else
+        Git.open(path)
+      end
+    rescue ArgumentError, Git::Error => e
+      raise Errors::GitError, "Failed to open repository at #{path}: #{e.message}"
+    end
+
+    # Check whether a path is a bare Git repository.
+    #
+    # @param path [String]
+    # @return [Boolean]
+    def bare_repo?(path)
+      File.exist?(File.join(path, "HEAD")) && File.directory?(File.join(path, "objects"))
+    end
+
+    # Resolve the git dir for a repo object (bare or non-bare).
+    #
+    # For bare repos:     returns the repo path directly.
+    # For non-bare repos: returns the .git directory path.
+    #
+    # @param repo [Git::Base]
+    # @return [String]
+    def git_dir(repo)
+      repo.repo.path.chomp("/")
+    end
+
+    # Create a Git worktree.
+    #
+    # Uses --detach to avoid conflicts when a branch is already checked out
+    # in the source clone or another worktree.
+    #
+    # @param repo [Git::Base] the source repository
+    # @param path [String] destination path for the worktree
+    # @param ref [String] branch name or commit SHA to check out
+    # @return [void]
+    def create_worktree(repo, path, ref)
+      FileUtils.mkdir_p(File.dirname(path))
+      sha = resolve_ref(repo, ref)
+      repo_dir = git_dir(repo)
+      _out, err, status = Open3.capture3("git", "--git-dir", repo_dir, "worktree", "add", "--detach", path, sha)
+      return if status.success?
+
+      raise Errors::GitError, "Failed to create worktree at #{path}: #{err}"
+    end
+
+    # Remove a Git worktree.
+    #
+    # @param repo [Git::Base] the source repository
+    # @param path [String] path of the worktree to remove
+    # @return [void]
+    def remove_worktree(repo, path)
+      repo_dir = git_dir(repo)
+      _out, err, status = Open3.capture3("git", "--git-dir", repo_dir, "worktree", "remove", "--force", path)
+      return if status.success?
+
+      raise Errors::GitError, "Failed to remove worktree at #{path}: #{err}"
+    end
+
+    # Fetch all remotes.
+    #
+    # @param repo [Git::Base] the repository to fetch
+    # @param label [String] display label for progress output
+    # @return [void]
+    def fetch(repo, label: "repository")
+      puts "Fetching: #{label}"
+      repo_dir = git_dir(repo)
+      _out, err, status = Open3.capture3("git", "--git-dir", repo_dir, "fetch", "--all")
+      raise Errors::FetchError.new(label, err) unless status.success?
+
+      puts "Fetch complete."
+    rescue Errors::FetchError
+      raise
+    rescue StandardError => e
+      raise Errors::FetchError.new(label, e.message)
+    end
+
+    # Resolve a commit reference (short SHA, branch, tag) to a full SHA.
+    #
+    # @param repo [Git::Base] the repository
+    # @param ref [String] the reference to resolve
+    # @return [String] full SHA
+    def resolve_ref(repo, ref)
+      cleaned = ref.to_s.delete_prefix('"').delete_suffix('"').delete_prefix("'").delete_suffix("'")
+      repo.object(cleaned).sha
+    rescue Git::Error => e
+      raise Errors::GitError, "Failed to resolve ref '#{ref}': #{e.message}. Try running fetch first."
+    end
+
+    # Resolve a branch name to the full SHA of its HEAD.
+    # Checks both local and remote branches.
+    #
+    # @param repo [Git::Base] the repository
+    # @param branch [String] the branch name
+    # @return [String] full SHA of the branch HEAD
+    def resolve_branch_head(repo, branch)
+      try_remote_branch(repo, branch) || resolve_local_branch(repo, branch)
+    end
+
+    # Read the default branch from HEAD in a bare repository.
+    #
+    # @param repo [Git::Base]
+    # @return [String] the default branch name (e.g. "main")
+    def default_branch(repo)
+      repo_dir = git_dir(repo)
+      out, _err, status = Open3.capture3("git", "--git-dir", repo_dir, "symbolic-ref", "--short", "HEAD")
+      return out.strip if status.success?
+
+      "main"
+    end
+
+    # @api private
+    def try_remote_branch(repo, branch)
+      repo.object("origin/#{branch}").sha
+    rescue Git::Error
+      nil
+    end
+
+    # @api private
+    def resolve_local_branch(repo, branch)
+      repo.object(branch).sha
+    rescue Git::Error => e
+      raise Errors::GitError, "Failed to resolve branch '#{branch}': #{e.message}. Try running fetch first."
+    end
+  end
+end

data/lib/Kobold/init.rb

@@ -1,36 +1,24 @@
 # frozen_string_literal: true
 
-require "tty-config"
-require 'fileutils'
-require 'git'
-
 module Kobold
   class << self
-    # create empty file with current
-    # file version in current dir
-    def init
-      kobold_default = <<-EOS
-[_kobold_config]
-format_version = #{Kobold::FORMAT_VERSION}
+    # Create a new .kobold TOML file in the current directory.
+    #
+    # This is a convenience wrapper around Kobold::Manager#init.
+    #
+    # @param dir [String] directory to create the file in (default: current dir)
+    # @return [Hash] { path:, created: }
+    def init(dir: Dir.pwd)
+      manager = Manager.new
+      result = manager.init(dir: dir)
+
+      if result[:created]
+        puts "Created .kobold at #{result[:path]}"
+      else
+        puts "WARNING: .kobold already exists at #{dir}"
+      end
 
-; must be unique, can be anything that doesnt start with underscore
-;[raylib-linux]
-;
-; required
-;repo = raysan5/raylib
-;source = https://github.com
-;
-; optional, remove slash at the end to rename the dir the repo is in
-;dir = external/linux-x64/
-;
-; one of these 2 is required
-;branch = something
-;commit = 'b8cd102'
-;
-; optional, makes unique trunk
-;label = linux-x64
-      EOS
-      File.write('.kobold', kobold_default)
+      result
     end
   end
 end