Kobold 0.3.3 → 0.4.0

data/README.md

@@ -1,35 +1,137 @@
 # Kobold
 
-TODO: Delete this and the text below, and describe your gem
+Kobold is a Git-based package manager for libraries and projects. It clones repositories into a local cache, creates Git worktrees for specific branches or commits, and symlinks them into your project directories. Deduplication is automatic - the same repo is only stored once regardless of how many projects reference it.
+
+Kobold provides both a **Ruby API** for programmatic use and a **CLI** for standalone command-line use.
+
+---
+
+### CLI Commands
+
+**init** — Create a new `.kobold` config file in the current directory.
+```
+kobold init
+kobold init --repo raysan5/raylib --branch master
+kobold init --repo raysan5/raylib --source https://gitlab.com --branch master
+```
+
+**invoke** — Process a `.kobold` file: clone repos, create worktrees, and symlink them into the project.
+```
+kobold invoke
+kobold invoke --config path/to/project/
+```
+
+**fetch** — Fetch updates for registered repositories.
+```
+kobold fetch
+kobold fetch raysan5/raylib
+```
+
+**register** — Register a repository in the database cache. Source defaults to `https://github.com`.
+```
+kobold register raysan5/raylib
+kobold register raysan5/raylib --source https://gitlab.com
+```
+
+**unregister** — Remove a repository from the database registry.
+```
+kobold unregister raysan5/raylib
+```
+
+**checkout** — Create a worktree for a repo and optionally symlink it.
+```
+kobold checkout raysan5/raylib --branch master --dir external/raylib
+```
+
+**branch** — Create a new branch in a cached repo with a worktree.
+```
+kobold branch raysan5/raylib --name my-feature --from main --dir /tmp/workspace
+```
+
+**list** — List registered repos, worktrees, or branches.
+```
+kobold list repos
+kobold list worktrees raysan5/raylib
+kobold list branches raysan5/raylib
+```
+
+**add** — Add a dependency to an existing `.kobold` file. Source defaults to `https://github.com`.
+```
+kobold add --repo raysan5/raylib --branch master --dir external/
+kobold add --repo raysan5/raylib --source https://gitlab.com --branch master
+```
+
+**remove** — Remove a dependency from a `.kobold` file.
+```
+kobold remove raylib
+kobold remove raylib --cleanup
+```
+
+**update** — Update dependency commit SHAs to the latest on their branch.
+```
+kobold update raylib
+kobold update
+```
+
+**clean** — Remove stale worktrees and optionally purge unreferenced repos.
+```
+kobold clean
+kobold clean --purge --config .
+```
+
+**db** — Manage databases (isolated cache directories).
+```
+kobold db create my-session
+kobold db delete my-session
+kobold db list
+```
+
+**config** — View or change global settings like the default source URL.
+```
+kobold config get-source
+kobold config set-source https://gitlab.com
+```
+
+**version** — Print version info.
+```
+kobold version
+```
+
+Use `--database NAME` before any command to operate on a specific database (default: `default`).
+
+```
+kobold --database orchestrator-session-1 invoke
+```
+
+---
+
+### Building and Installing Locally
+
+Clone the repository and install dependencies:
+
+```
+git clone https://github.com/CatsAtTheRodeo/Kobold.git
+cd Kobold
+bundle install
+```
+
+Build the gem:
+
+```
+gem build Kobold.gemspec
+```
+
+Install the built gem:
+
+```
+gem install Kobold-0.4.0.gem
+```
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/Kobold`. To experiment with that code, run `bin/console` for an interactive prompt.
+The `kobold` executable will be available on your `PATH` after installation.
+
+---
 
-## Installation
-
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
-
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/Kobold.
-
-## License
+### License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -2,7 +2,24 @@
 
 require "bundler/gem_tasks"
 require "rubocop/rake_task"
+require "rspec/core/rake_task"
+require "fileutils"
 
-RuboCop::RakeTask.new
+RuboCop::RakeTask.new do |task|
+  task.options = [
+    "--format", "progress",
+    "--format", "html", "-o", "tmp/reports/rubocop_results.html"
+  ]
+end
 
-task default: :rubocop
+RSpec::Core::RakeTask.new(:spec)
+
+# Ensure reports directory exists before running tasks
+task :setup_reports do
+  FileUtils.mkdir_p("tmp/reports")
+end
+
+task spec: :setup_reports
+task rubocop: :setup_reports
+
+task default: %i[spec rubocop]

data/exe/kobold

@@ -1,60 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require 'Kobold'
-require 'tty-option'
-#require 'pry'
+require "Kobold"
 
-module Kobold
-  class Command
-    include TTY::Option
-
-    usage do
-      program "kobold"
-
-      commands "init", "invoke"
-
-    end
-
-    argument :command do
-      optional
-      desc "Accepts commands for Kobold to execute."
-    end
-
-    flag :help do
-      short "-h"
-      long "--help"
-      desc "Print usage."
-    end
-
-    def run
-      if params[:help]
-        print help
-      elsif params.errors.any?
-        puts params.errors.summary
-      else
-        #pp params.to_h
-      end
-    end
-  end
-end
-
-
-cmd = Kobold::Command.new
-parse = cmd.parse
-run = cmd.run
-
-if cmd.params[:command] == nil || cmd.params == "invoke"
-  Kobold.invoke
-else
-  case cmd.params[:command]
-  when "add"
-  when "remove"
-  when "update"
-  when "list"
-    Kobold.list
-  when "init"
-    Kobold.init
-  else
-    print cmd.help
-  end
-end
+Kobold::CLI.new(ARGV).run

data/lib/Kobold/cli/admin_commands.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Kobold
+  class CLI
+    # Database and config management commands.
+    module AdminCommands
+      private
+
+      def cmd_db
+        sub, remaining = extract_positional(@args)
+        name_arg, remaining = extract_positional(remaining) if sub
+        opts = parse_flags(remaining || [], {}, {})
+        return show_db_help_text(sub) if opts[:help] || sub.nil?
+
+        dispatch_db(sub, name_arg)
+      end
+
+      DB_HELP = <<~HELP
+        Usage: kobold db <subcommand> [NAME]
+
+        Manage databases.
+
+        Subcommands:
+          create NAME    Create a new named database
+          delete NAME    Delete a named database and all its contents
+          list           List all databases
+
+        Options:
+          -h, --help     Show this help
+      HELP
+
+      def show_db_help_text(sub)
+        puts DB_HELP
+        sub
+      end
+
+      def dispatch_db(sub, name_arg)
+        case sub
+        when "create" then db_create(name_arg)
+        when "delete" then db_delete(name_arg)
+        when "list"   then db_list
+        else
+          error "Unknown db subcommand: #{sub}"
+          hint "Available: create, delete, list"
+          exit EXIT_USAGE
+        end
+      end
+
+      def db_create(name_arg)
+        require_arg!(name_arg, "NAME", "kobold db create NAME")
+        result = Manager.create_database(name_arg)
+        success "Created database '#{result[:name]}' at #{result[:path]}"
+      end
+
+      def db_delete(name_arg)
+        require_arg!(name_arg, "NAME", "kobold db delete NAME")
+        result = Manager.delete_database(name_arg)
+        success "Deleted database '#{result[:name]}'"
+      end
+
+      def db_list
+        databases = Manager.list_databases
+        if databases.empty?
+          info "No databases found."
+        else
+          puts "Databases:"
+          databases.each do |name|
+            marker = name == "default" ? " (default)" : ""
+            puts "  #{name}#{marker}"
+          end
+        end
+      end
+
+      def cmd_config
+        sub, remaining = extract_positional(@args)
+        value_arg, remaining = extract_positional(remaining) if sub
+        opts = parse_flags(remaining || [], {}, {})
+        return show_config_help_text(sub) if opts[:help] || sub.nil?
+
+        dispatch_config(sub, value_arg)
+      end
+
+      CONFIG_HELP = <<~HELP
+        Usage: kobold config <subcommand> [VALUE]
+
+        View and change global settings.
+
+        Subcommands:
+          get-source         Show the default source URL
+          set-source URL     Set the default source URL
+
+        Options:
+          -h, --help         Show this help
+      HELP
+
+      def show_config_help_text(sub)
+        puts CONFIG_HELP
+        sub
+      end
+
+      def dispatch_config(sub, value_arg)
+        case sub
+        when "get-source" then puts "Default source: #{Settings.default_source}"
+        when "set-source" then config_set_source(value_arg)
+        else
+          error "Unknown config subcommand: #{sub}"
+          hint "Available: get-source, set-source"
+          exit EXIT_USAGE
+        end
+      end
+
+      def config_set_source(value_arg)
+        require_arg!(value_arg, "URL", "kobold config set-source https://github.com")
+        Settings.default_source = value_arg
+        success "Default source set to: #{value_arg}"
+      end
+
+      def cmd_version
+        puts "Kobold:        #{VERSION}"
+        puts "Kobold Format: #{FORMAT_VERSION}"
+      end
+    end
+  end
+end

data/lib/Kobold/cli/checkout_commands.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Kobold
+  class CLI
+    # Checkout and branch creation commands.
+    module CheckoutCommands
+      private
+
+      def cmd_checkout
+        repo_arg, remaining = extract_positional(@args)
+        opts = parse_flags(remaining, {}, { "branch" => nil, "commit" => nil, "label" => nil, "dir" => nil })
+        return puts(CHECKOUT_HELP) if opts[:help]
+
+        require_arg!(repo_arg, "REPO", "kobold checkout REPO [--branch NAME] [--commit SHA] [--dir PATH]")
+
+        result = manager.checkout(
+          repo_arg, branch: opts["branch"], commit: opts["commit"], label: opts["label"], dir: opts["dir"]
+        )
+        success "Worktree created at #{result[:worktree_path]}"
+        info "Symlinked to #{result[:symlink_path]}" if result[:symlink_path]
+      end
+
+      CHECKOUT_HELP = <<~HELP
+        Usage: kobold checkout REPO [options]
+
+        Create a worktree for a repo and optionally symlink it.
+
+        Arguments:
+          REPO             Repository identifier (e.g. 'raysan5/raylib')
+
+        Options:
+          --branch NAME    Branch to check out
+          --commit SHA     Commit SHA to check out
+          --label NAME     Label for the worktree (requires --commit)
+          --dir PATH       Destination path for a symlink
+          -h, --help       Show this help
+      HELP
+
+      def cmd_branch
+        repo_arg, remaining = extract_positional(@args)
+        opts = parse_flags(remaining, { "name" => :required }, { "from" => "main", "dir" => nil })
+        return puts(BRANCH_HELP) if opts[:help]
+
+        require_arg!(repo_arg, "REPO", "kobold branch REPO --name BRANCH [--from REF] [--dir PATH]")
+        require_option!(opts["name"], "--name", "kobold branch #{repo_arg} --name my-branch")
+
+        result = manager.create_branch(repo_arg, name: opts["name"], from: opts["from"], dir: opts["dir"])
+        display_branch_result(result)
+      end
+
+      BRANCH_HELP = <<~HELP
+        Usage: kobold branch REPO --name BRANCH [options]
+
+        Create a new branch in a cached repo with a worktree.
+
+        Arguments:
+          REPO             Repository identifier (e.g. 'raysan5/raylib')
+
+        Options:
+          --name BRANCH    Name for the new branch (required)
+          --from REF       Source branch/ref to branch from (default: 'main')
+          --dir PATH       Destination path for a symlink
+          -h, --help       Show this help
+      HELP
+
+      def display_branch_result(result)
+        success "Branch '#{result[:branch]}' created for #{result[:slug]}"
+        info "Worktree at #{result[:worktree_path]}"
+        info "Symlinked to #{result[:symlink_path]}" if result[:symlink_path]
+      end
+    end
+  end
+end

data/lib/Kobold/cli/error_handling.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Kobold
+  class CLI
+    # Error handling dispatch table for CLI.
+    module ErrorHandling
+      ERROR_HANDLERS = [
+        [Errors::InvalidFormat,      ->(e) { CLI.report_format_error(e) }],
+        [Errors::ConfigError,        ->(e) { CLI.report_error("Config error: #{e.message}") }],
+        [Errors::RepoNotFound,       ->(e) { CLI.report_with_hint(e.message, "Run 'kobold register' first.") }],
+        [Errors::WorktreeExists,     ->(e) { CLI.report_error(e.message) }],
+        [Errors::CloneError,         ->(e) { CLI.report_with_hint(e.message, "Check URL and network.") }],
+        [Errors::FetchError,         ->(e) { CLI.report_with_hint(e.message, "Check network and retry.") }],
+        [Errors::GitError,           ->(e) { CLI.report_error("Git error: #{e.message}") }],
+        [Errors::DatabaseNotFound,   ->(e) { CLI.report_error(e.message) }],
+        [Errors::DatabaseExists,     ->(e) { CLI.report_error(e.message) }],
+        [Errors::DependencyNotFound, ->(e) { CLI.report_with_hint(e.message, "Check dependency name.") }],
+        [Errors::LinkError,          ->(e) { CLI.report_error("Link error: #{e.message}") }]
+      ].freeze
+
+      private
+
+      def handle_error(exception)
+        handler = find_error_handler(exception)
+        return raise unless handler
+
+        handler.call(exception)
+        exit EXIT_ERROR
+      end
+
+      def find_error_handler(exception)
+        ERROR_HANDLERS.find { |klass, _| exception.is_a?(klass) }&.last
+      end
+    end
+
+    def self.report_error(msg)
+      $stderr.puts "\e[31m\u2717\e[0m #{msg}" # rubocop:disable Style/StderrPuts
+    end
+
+    def self.report_format_error(err)
+      report_error("Format error: #{err.message}")
+      $stderr.puts "  \e[90mYour .kobold file may need format version #{FORMAT_VERSION}.\e[0m" # rubocop:disable Style/StderrPuts
+    end
+
+    def self.report_with_hint(msg, hint_msg)
+      report_error(msg)
+      $stderr.puts "  \e[90m#{hint_msg}\e[0m" # rubocop:disable Style/StderrPuts
+    end
+  end
+end

data/lib/Kobold/cli/flag_parser.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Kobold
+  class CLI
+    # Global and subcommand flag parsing.
+    module FlagParser
+      private
+
+      def parse_global_flags
+        state = { remaining: [], seen_command: false, i: 0 }
+        process_global_args(state) while state[:i] < @argv.length
+        @command = state[:remaining].shift
+        @args = state[:remaining]
+      end
+
+      def process_global_args(state)
+        arg = @argv[state[:i]]
+        if state[:seen_command]
+          handle_post_command_arg(arg, state)
+        else
+          handle_global_arg(arg, state)
+        end
+        state[:i] += 1
+      end
+
+      def handle_post_command_arg(arg, state)
+        case arg
+        when "--database" then @database = consume_next_arg(state, "--database")
+        when /\A--database=(.+)\z/ then @database = Regexp.last_match(1)
+        else state[:remaining] << arg
+        end
+      end
+
+      def handle_global_arg(arg, state)
+        case arg
+        when "--database" then @database = consume_next_arg(state, "--database")
+        when /\A--database=(.+)\z/ then @database = Regexp.last_match(1)
+        when "-h", "--help" then print_help_and_exit
+        else
+          state[:remaining] << arg
+          state[:seen_command] = true unless arg.start_with?("-")
+        end
+      end
+
+      def print_help_and_exit
+        print_help
+        exit EXIT_SUCCESS
+      end
+
+      def consume_next_arg(state, flag_name)
+        state[:i] += 1
+        if state[:i] >= @argv.length
+          error "Missing value for #{flag_name}"
+          exit EXIT_USAGE
+        end
+        @argv[state[:i]]
+      end
+
+      # Simple flag parser for subcommand options.
+      def parse_flags(argv, _required, defaults, boolean_flags = [])
+        opts = defaults.dup
+        opts[:help] = false
+        boolean_set = boolean_flags.to_set
+        idx = 0
+
+        while idx < argv.length
+          idx = parse_single_flag(argv, idx, opts, boolean_set)
+          idx += 1
+        end
+
+        opts
+      end
+
+      def parse_single_flag(argv, idx, opts, boolean_set)
+        arg = argv[idx]
+        case arg
+        when "-h", "--help"
+          opts[:help] = true
+        when /\A--([a-z][-a-z0-9]*)=(.+)\z/
+          opts[Regexp.last_match(1)] = Regexp.last_match(2)
+        when /\A--([a-z][-a-z0-9]*)\z/
+          idx = parse_named_flag(argv, idx, Regexp.last_match(1), opts, boolean_set)
+        end
+        idx
+      end
+
+      def parse_named_flag(argv, idx, key, opts, boolean_set)
+        if boolean_set.include?(key)
+          opts[key] = true
+          return idx
+        end
+
+        idx = consume_flag_value(argv, idx, key)
+        opts[key] = argv[idx]
+        idx
+      end
+
+      def consume_flag_value(argv, idx, key)
+        idx += 1
+        return idx if idx < argv.length
+
+        error "Missing value for --#{key}"
+        exit EXIT_USAGE
+      end
+    end
+  end
+end