Kobold 0.3.3 → 0.4.0

data/.rules/default/rubocop.md

@@ -0,0 +1,228 @@
+# Ruby Style & RuboCop Compliance Rules
+
+This file defines the Ruby coding standards enforced by RuboCop in this project. You **must** follow these rules when writing or editing any Ruby source code (excluding `spec/` files, which are exempt from Metrics cops).
+
+---
+
+## 1. General
+
+- **Target Ruby version:** 3.0+
+- **String literals:** Always use double quotes (`"`), including inside interpolation.
+- **Line length:** Maximum **120 characters** per line.
+- Do **not** add top-level documentation comments to classes or modules (`Style/Documentation` is disabled).
+
+---
+
+## 2. Method Length
+
+**Max 10 lines** per method body (excluding `def`/`end`).
+
+- If a method exceeds 10 lines, extract logic into private helper methods.
+- Each helper should have a single, clear responsibility.
+
+### Example — Too long:
+
+```ruby
+def process(data)
+  # 15 lines of mixed validation, transformation, and output
+end
+```
+
+### Example — Correct:
+
+```ruby
+def process(data)
+  validate(data)
+  result = transform(data)
+  output(result)
+end
+
+private
+
+def validate(data)
+  # ...
+end
+
+def transform(data)
+  # ...
+end
+
+def output(result)
+  # ...
+end
+```
+
+---
+
+## 3. ABC Size (Assignment Branch Condition)
+
+**Max 17.** This measures a combination of assignments, branches (method calls), and conditions.
+
+To reduce ABC size:
+
+- Extract sub-expressions into local variables or helper methods.
+- Avoid deeply chained method calls on a single line.
+- Move conditional logic into dedicated predicate methods.
+
+---
+
+## 4. Cyclomatic Complexity
+
+**Max 7.** Counts the number of independent code paths (each `if`, `elsif`, `unless`, `when`, `while`, `until`, `for`, `rescue`, `&&`, `||` adds 1).
+
+To reduce cyclomatic complexity:
+
+- Use early returns / guard clauses instead of nested `if`/`else`.
+- Extract `case`/`when` branches into a dispatch hash or strategy pattern.
+- Break complex conditionals into named predicate methods.
+
+### Example — Too complex:
+
+```ruby
+def dispatch(cmd)
+  if cmd == "a"
+    do_a
+  elsif cmd == "b"
+    do_b
+  elsif cmd == "c"
+    do_c
+  # ... 10 more branches
+  end
+end
+```
+
+### Example — Correct:
+
+```ruby
+DISPATCH = {
+  "a" => :do_a,
+  "b" => :do_b,
+  "c" => :do_c,
+}.freeze
+
+def dispatch(cmd)
+  handler = DISPATCH[cmd]
+  raise "Unknown command: #{cmd}" unless handler
+  send(handler)
+end
+```
+
+---
+
+## 5. Perceived Complexity
+
+**Max 8.** Similar to cyclomatic complexity but also weighs `else` and `when` branches.
+
+Same mitigation strategies as cyclomatic complexity apply.
+
+---
+
+## 6. Class Length
+
+**Max 100 lines** (excluding comments and blank lines).
+
+- If a class exceeds 100 lines, extract cohesive groups of methods into modules (mixins) or separate classes.
+- Use composition: delegate behavior to collaborator objects.
+
+---
+
+## 7. Block Nesting
+
+**Max 3 levels** of block nesting.
+
+To reduce nesting:
+
+- Use `next` / `return` guard clauses to skip iterations early.
+- Extract inner blocks into helper methods.
+
+### Example — Too nested:
+
+```ruby
+items.each do |item|
+  if item.valid?
+    item.parts.each do |part|
+      if part.active?
+        # level 4 — violation
+      end
+    end
+  end
+end
+```
+
+### Example — Correct:
+
+```ruby
+items.each do |item|
+  next unless item.valid?
+  process_parts(item.parts)
+end
+
+def process_parts(parts)
+  parts.each do |part|
+    next unless part.active?
+    # ...
+  end
+end
+```
+
+---
+
+## 8. Parameter Lists
+
+**Max 5 parameters** per method.
+
+To reduce parameters:
+
+- Group related parameters into a hash or keyword arguments with a config/options object.
+- Consider whether some parameters should be instance state instead.
+
+### Example — Too many:
+
+```ruby
+def add(config_path:, name:, repo:, source:, branch:, commit:, label:, dir:)
+```
+
+### Example — Correct:
+
+```ruby
+def add(config_path:, name:, repo:, **options)
+  source = options[:source]
+  branch = options[:branch]
+  # ...
+end
+```
+
+Or use a dedicated parameter object / struct.
+
+---
+
+## 9. Naming
+
+- Do **not** prefix writer methods with `set_`. Use Ruby's assignment-style naming: `def foo=(value)` instead of `def set_foo(value)`.
+- File names must use `snake_case` (exception: `lib/Kobold.rb` is excluded).
+
+---
+
+## 10. Style
+
+- Do **not** write empty `else` clauses. If an `else` branch does nothing, omit it entirely.
+- Prefer guard clauses (`return unless ...`) over wrapping entire method bodies in `if`.
+- Use `$stderr.puts` (not `warn`) inside custom `warn`/`error`/`hint` output methods to avoid infinite recursion with Kernel#warn.
+
+---
+
+## 11. Layout
+
+- Maximum line length: **120 characters**.
+- When a string interpolation makes a line too long, split it with a backslash continuation:
+
+```ruby
+success "#{name}: #{short_sha(old)} -> " \
+        "#{short_sha(new)} (#{branch})"
+```
+
+---
+
+## 12. Spec Files
+
+Spec files under `spec/` are **exempt** from all Metrics cops. Write tests for clarity and completeness without worrying about method/block length limits.

data/.rules/docs/kobold_api.md

@@ -0,0 +1,491 @@
+# Kobold Ruby API Reference
+
+Kobold is a Git-based package manager gem. It clones repositories as bare caches, creates Git worktrees for specific branches/commits, and symlinks them into project directories. All write operations (merge, commit, push) are **out of scope** — Kobold is read-only with respect to repo content.
+
+**Gem:** `Kobold` (v0.4.0)
+**Ruby:** >= 3.0
+**Dependencies:** `git` (~> 4.3), `toml-rb` (~> 3.0)
+
+---
+
+## Require
+
+```ruby
+require "Kobold"
+```
+
+---
+
+## Constants
+
+| Constant | Value | Description |
+|---|---|---|
+| `Kobold::VERSION` | `"0.4.0"` | Gem version |
+| `Kobold::FORMAT_VERSION` | `"0.4.0"` | `.kobold` config file format version |
+| `Kobold::KOBOLD_DIR` | `~/.local/share/Kobold` | Root storage directory |
+
+---
+
+## Kobold::Manager
+
+Primary API entry point. All repo operations go through a `Manager` instance.
+
+### Constructor
+
+```ruby
+manager = Kobold::Manager.new(database: "my-db")
+```
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `database:` | `String` | `"default"` | Named database (isolated cache namespace) |
+
+Creates the database on disk if it does not exist.
+
+---
+
+### Registration
+
+#### `register(repo, source:)` → `Hash`
+
+Register a repository in the database.
+
+```ruby
+manager.register("owner/repo", source: "https://github.com")
+# => { slug: "owner-repo", source_url: "https://github.com/owner/repo.git", already_registered: false }
+```
+
+| Param | Type | Description |
+|---|---|---|
+| `repo` | `String` | Repo identifier, e.g. `"owner/repo"` |
+| `source:` | `String` | Git host base URL |
+
+#### `unregister(repo)` → `Hash`
+
+```ruby
+manager.unregister("owner/repo")
+# => { slug: "owner-repo", removed: true }
+```
+
+Raises `Kobold::Errors::RepoNotFound` if not registered.
+
+---
+
+### Fetching
+
+#### `fetch(repo)` → `Hash`
+
+Fetch latest objects for a single registered repo. Clones if not yet cached.
+
+```ruby
+manager.fetch("owner/repo")
+# => { slug: "owner-repo", action: :fetched }  # or action: :cloned
+```
+
+#### `fetch_all(config_path: Dir.pwd)` → `Array<Hash>`
+
+Fetch all repos referenced in a `.kobold` config file. Registers any unregistered repos automatically.
+
+```ruby
+manager.fetch_all(config_path: "/path/to/.kobold")
+# => [{ name: "dep-name", slug: "owner-repo", action: :fetched }, ...]
+```
+
+---
+
+### Checkout & Worktrees
+
+#### `checkout(repo, branch: nil, commit: nil, label: nil, dir: nil)` → `Hash`
+
+Create a worktree for a repo. Clones the repo if not yet cached. Optionally creates a symlink.
+
+```ruby
+result = manager.checkout("owner/repo", branch: "main", dir: "/project/vendor/repo")
+# => { slug: "owner-repo", worktree_path: "/home/.../.local/share/Kobold/...", symlink_path: "/project/vendor/repo" }
+```
+
+| Param | Type | Description |
+|---|---|---|
+| `repo` | `String` | Repo identifier |
+| `branch:` | `String?` | Branch to check out |
+| `commit:` | `String?` | Specific commit SHA |
+| `label:` | `String?` | Named label (requires `commit:`) |
+| `dir:` | `String?` | If set, symlink the worktree here |
+
+Resolution priority: `commit` > `branch` > default branch. Worktrees are detached-HEAD checkouts.
+
+**Worktree storage paths:**
+
+- Branch: `<repo_cache>/worktrees/branches/<branch>`
+- Commit: `<repo_cache>/worktrees/commits/<sha>`
+- Label: `<repo_cache>/worktrees/labelled/<label>/<sha>`
+
+#### `create_branch(repo, name:, from: "main", dir: nil)` → `Hash`
+
+Create a new branch in the bare cache, then create a worktree for it.
+
+```ruby
+result = manager.create_branch("owner/repo", name: "feature-x", from: "main", dir: "/project/vendor/repo")
+# => { slug: "owner-repo", branch: "feature-x", worktree_path: "...", symlink_path: "..." }
+```
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `name:` | `String` | — | New branch name |
+| `from:` | `String` | `"main"` | Source ref (branch, tag, or SHA) |
+| `dir:` | `String?` | `nil` | Symlink destination |
+
+If the branch already exists, it is reused (no error).
+
+#### `remove_worktree(repo, dir:)` → `Hash`
+
+Remove a worktree. If `dir:` is a symlink, follows it to the worktree and removes both.
+
+```ruby
+manager.remove_worktree("owner/repo", dir: "/project/vendor/repo")
+# => { slug: "owner-repo", removed_worktree: "...", removed_symlink: true }
+```
+
+---
+
+### Listing
+
+#### `list_repos` → `Hash`
+
+All registered repos in the database.
+
+```ruby
+manager.list_repos
+# => { "owner-repo" => { "source_url" => "https://github.com/owner/repo.git" } }
+```
+
+#### `list_worktrees(repo)` → `Array<String>`
+
+All worktree paths for a repo.
+
+```ruby
+manager.list_worktrees("owner/repo")
+# => ["/home/.../.local/share/Kobold/.../worktrees/branches/main"]
+```
+
+#### `list_branches(repo)` → `Array<String>`
+
+All branch names in the bare cache.
+
+```ruby
+manager.list_branches("owner/repo")
+# => ["main", "develop", "feature-x"]
+```
+
+---
+
+### Lifecycle (Config-Based)
+
+These methods operate on `.kobold` TOML config files.
+
+#### `add(config_path:, repo:, source:, name: nil, **options)` → `Hash`
+
+Add a dependency to a `.kobold` config file. Registers and clones the repo.
+
+```ruby
+manager.add(
+  config_path: "/project/.kobold",
+  repo: "owner/repo",
+  source: "https://github.com",
+  name: "my-dep",
+  branch: "main",
+  commit: "abc1234",
+  dir: "vendor/"
+)
+# => { config_path: "...", name: "my-dep", slug: "owner-repo", action: :cloned }
+```
+
+| Option | Type | Description |
+|---|---|---|
+| `name:` | `String?` | Dependency name (defaults to repo basename) |
+| `branch:` | `String?` | Branch name |
+| `commit:` | `String?` | Pinned commit SHA |
+| `label:` | `String?` | Label (requires commit) |
+| `dir:` | `String?` | Symlink directory in config |
+
+#### `remove(config_path:, dependency_name:, cleanup: false)` → `Hash`
+
+Remove a dependency from a `.kobold` config. With `cleanup: true`, also removes the worktree and symlink.
+
+```ruby
+manager.remove(config_path: "/project/.kobold", dependency_name: "my-dep", cleanup: true)
+# => { config_path: "...", name: "my-dep", removed_worktree: "...", removed_symlink: true }
+```
+
+#### `update(config_path:, dependency_name:)` → `Hash`
+
+Update a dependency's commit SHA to the latest HEAD of its configured branch. Fetches first.
+
+```ruby
+manager.update(config_path: "/project/.kobold", dependency_name: "my-dep")
+# => { config_path: "...", name: "my-dep", old_commit: "abc...", new_commit: "def...", branch: "main" }
+```
+
+Raises `Kobold::Errors::DependencyNotFound` if missing. Raises `Kobold::Errors::ConfigError` if no branch is set.
+
+#### `update_all(config_path: Dir.pwd)` → `Array<Hash>`
+
+Update all dependencies that have a `branch` field. Errors are caught and returned inline.
+
+```ruby
+manager.update_all(config_path: "/project/.kobold")
+# => [{ config_path: "...", name: "my-dep", old_commit: "...", new_commit: "...", branch: "main" }, ...]
+```
+
+---
+
+### Invoke
+
+#### `invoke(config_path: Dir.pwd)` → `Array<Hash>`
+
+Process a `.kobold` config end-to-end: register, clone, create worktrees, and symlink all dependencies. Recursively processes `includes`.
+
+```ruby
+manager.invoke(config_path: "/project/.kobold")
+# => [{ name: "dep", slug: "owner-repo", worktree_path: "...", symlink_path: "..." }, ...]
+```
+
+---
+
+### Init
+
+#### `init(dir: Dir.pwd)` → `Hash`
+
+Create a new `.kobold` TOML template file.
+
+```ruby
+manager.init(dir: "/project")
+# => { path: "/project/.kobold", created: true }
+```
+
+Returns `created: false` if the file already exists.
+
+---
+
+### Config Generation
+
+#### `generate_config(path:, dependencies: [], includes: [])` → `Hash`
+
+Programmatically generate a `.kobold` config file.
+
+```ruby
+manager.generate_config(
+  path: "/project/.kobold",
+  dependencies: [
+    { name: "my-dep", repo: "owner/repo", source: "https://github.com", branch: "main" }
+  ],
+  includes: ["subdir/"]
+)
+# => { path: "/project/.kobold", dependencies_count: 1 }
+```
+
+Each dependency hash must include `:name`, `:repo`, `:source`. Optional: `:branch`, `:commit`, `:label`, `:dir`.
+
+---
+
+### Cleaning
+
+#### `clean(config_path: nil)` → `Hash`
+
+Purge repos not referenced by the given config. Without a config path, returns an empty purge list.
+
+```ruby
+manager.clean(config_path: "/project/.kobold")
+# => { purged_repos: [{ slug: "unused-repo" }] }
+```
+
+---
+
+## Class Methods on Kobold::Manager
+
+### Database Management
+
+```ruby
+Kobold::Manager.create_database("my-db")
+# => { name: "my-db", path: "...", created: true }
+
+Kobold::Manager.delete_database("my-db")
+# => { name: "my-db", deleted: true }
+
+Kobold::Manager.list_databases
+# => ["default", "my-db"]
+```
+
+`create_database` raises `Kobold::Errors::DatabaseExists` if it already exists.
+`delete_database` raises `Kobold::Errors::DatabaseNotFound` if missing.
+
+---
+
+## Kobold::Settings
+
+Module for global user-level settings stored at `~/.local/share/Kobold/config.toml`.
+
+```ruby
+Kobold::Settings.default_source
+# => "https://github.com"
+
+Kobold::Settings.default_source = "https://gitlab.com"
+
+Kobold::Settings.get("defaults.source")
+# => "https://gitlab.com"
+
+Kobold::Settings.set("defaults.source", "https://github.com")
+```
+
+---
+
+## Kobold::Database
+
+Lower-level API. Normally accessed through `Manager`, but available directly.
+
+```ruby
+db = Kobold::Database.new("my-db")
+db.setup
+db.register_repo("owner-repo", "https://github.com/owner/repo.git")
+db.list_repos            # => { "owner-repo" => { "source_url" => "..." } }
+repo = db.repo("owner-repo")  # => Kobold::Repo instance
+db.unregister_repo("owner-repo")
+db.delete
+
+Kobold::Database.slugify("owner/repo")  # => "owner-repo"
+Kobold::Database.list_databases          # => ["default", ...]
+Kobold::Database.exists?("my-db")        # => true/false
+```
+
+---
+
+## Kobold::Repo
+
+Represents a cached repository. Obtained via `Database#repo(slug)`.
+
+```ruby
+repo = db.repo("owner-repo")
+
+repo.slug              # => "owner-repo"
+repo.source_url        # => "https://github.com/owner/repo.git"
+repo.path              # => "/home/.../.local/share/Kobold/databases/my-db/repos/owner-repo"
+repo.source_path       # => ".../source" (bare clone location)
+repo.cloned?           # => true/false
+
+repo.clone             # Clone if not cached; returns Git::Base
+repo.fetch             # Fetch all remotes
+
+repo.create_worktree(branch: "main")
+repo.create_worktree(commit: "abc1234")
+repo.create_worktree(commit: "abc1234", label: "v1")
+repo.remove_worktree("/path/to/worktree")
+
+repo.create_branch("feature-x", from: "main")  # => "feature-x"
+
+repo.list_worktrees    # => ["/path/to/worktree", ...]
+repo.list_branches     # => ["main", "develop", ...]
+repo.resolve_branch_head("main")  # => "abc1234..." (full SHA)
+
+repo.worktree_path_for(branch: "main")  # => predicted path without creating
+repo.purge             # Delete entire repo cache
+```
+
+---
+
+## Kobold::Linker
+
+Stateless symlink utilities.
+
+```ruby
+Kobold::Linker.link("/source/path", "/dest/path")       # => "/dest/path"
+Kobold::Linker.link("/source/path", "/dest/dir/")        # => "/dest/dir/path" (basename)
+Kobold::Linker.unlink("/dest/path")                      # removes symlink
+Kobold::Linker.relink("/new/source", "/dest/path")       # unlink + link
+Kobold::Linker.valid?("/dest/path")                      # => true if symlink target exists
+```
+
+---
+
+## Kobold::Config
+
+Reads and manipulates `.kobold` TOML config files.
+
+```ruby
+config = Kobold::Config.read("/project/.kobold")
+config.format_version   # => "0.4.0"
+config.includes         # => ["subdir/"]
+config.dependencies     # => { "name" => { "repo" => "...", ... } }
+config.path             # => "/project/.kobold"
+
+config.each_dependency { |name, dep| ... }
+config.dependency("name")       # => Hash or nil
+config.dependency?("name")      # => true/false
+config.add_dependency("name", { "repo" => "owner/repo", "source" => "https://github.com" })
+config.remove_dependency("name")
+config.update_dependency("name", "commit", "abc1234")
+config.to_h                     # => full Hash for serialization
+
+Kobold::Config.write("/project/.kobold", config)
+Kobold::Config.generate(dependencies: [...], includes: [...])
+```
+
+**Dependency required keys:** `repo`, `source`
+**Dependency optional keys:** `dir`, `branch`, `commit`, `label`
+**Constraint:** `label` requires `commit` to be set.
+
+---
+
+## Kobold::GitOps
+
+Low-level stateless Git operations. All methods are `module_function`.
+
+```ruby
+Kobold::GitOps.clone(url, path)             # => Git::Base (bare clone)
+Kobold::GitOps.open(path)                   # => Git::Base (bare or non-bare)
+Kobold::GitOps.bare_repo?(path)             # => true/false
+Kobold::GitOps.git_dir(repo)                # => String (path to .git or bare dir)
+Kobold::GitOps.fetch(repo, label: "...")    # fetch --all
+Kobold::GitOps.resolve_ref(repo, ref)       # => full SHA
+Kobold::GitOps.resolve_branch_head(repo, branch)  # => full SHA (checks origin/ first)
+Kobold::GitOps.default_branch(repo)         # => "main" (reads symbolic-ref HEAD)
+Kobold::GitOps.create_worktree(repo, path, ref)   # worktree add --detach
+Kobold::GitOps.remove_worktree(repo, path)  # worktree remove --force
+```
+
+---
+
+## Errors
+
+All under `Kobold::Errors`:
+
+| Error | Raised When |
+|---|---|
+| `RepoNotFound` | Repo slug not in database or not cloned |
+| `WorktreeExists` | Worktree path already exists |
+| `ConfigError` | Missing/invalid `.kobold` config |
+| `DatabaseNotFound` | Database directory does not exist |
+| `DatabaseExists` | Trying to create a database that exists |
+| `InvalidFormat` | Config format_version mismatch |
+| `CloneError` | `git clone` fails |
+| `FetchError` | `git fetch` fails |
+| `GitError` | General git operation failure |
+| `DependencyNotFound` | Named dependency missing from config |
+| `LinkError` | Symlink operation failure |
+
+---
+
+## Convenience Wrappers (Module-Level)
+
+These print to stdout and are thin wrappers around `Manager`:
+
+```ruby
+Kobold.init(dir: "/project")
+Kobold.invoke(config_path: "/project", database_name: "default")
+Kobold.fetch(config_path: "/project", database_name: "default")
+```
+
+---
+
+## Slugification
+
+Repo identifiers (`"owner/repo"`) are converted to slugs (`"owner-repo"`) via `Database.slugify`. All internal lookups use slugs.