Rosett-AI - Setup Guide

Prerequisites

Ruby 3.3.10 via rbenv

This project requires Ruby 3.3.10. We use rbenv for Ruby version management.

Installing rbenv

# On Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y git curl autoconf bison build-essential \
  libssl-dev libyaml-dev libreadline6-dev zlib1g-dev \
  libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev

# Install rbenv
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

# Install ruby-build plugin
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Installing Ruby 3.3.10

# Install Ruby 3.3.10
rbenv install 3.3.10

# Verify installation
rbenv versions

# The .ruby-version file will automatically select 3.3.10 in this directory
cd ~/.claude
ruby --version  # Should show ruby 3.3.10

Installation

1. Clone/Initialize Repository

If you haven't already initialized the repository:

cd ~/.claude
git init

2. Install Dependencies

bundle install

This installs all Bundler groups including :desktop (GTK4). If you do not need desktop features or lack the GTK4 system libraries, exclude the group:

bundle config set --local without 'desktop'
bundle install

For desktop development, install system dependencies first:

sudo apt-get install -y libgirepository1.0-dev libgtk-4-dev
bundle install

3. Install Git Hooks (CRITICAL)

Important: This step is mandatory. Without git hooks, code quality checks will not run before commits.

# Install overcommit hooks
overcommit --install

# Verify hooks are installed correctly
ls -la .git/hooks/pre-commit && echo "✓ Pre-commit hook installed" || echo "✗ Hook installation failed"

# Test the hooks work
bundle exec overcommit --run

4. Verify Installation

# Check CLI works
bin/raictl version

# Run tests
bundle exec rspec

# Run mutation testing
bundle exec mutant run

# Run linter
bundle exec rubocop

# Check for CVEs
bundle exec bundler-audit check

Configuration

Global Settings

Edit settings.json to configure global Claude Code permissions:

{
  "permissions": {
    "allow": ["Bash(bundle:*)"],
    "deny": ["Read(/home/user/.ssh/**)"]
  }
}

Local Overrides

Create settings.local.json for machine-specific settings (gitignored):

{
  "permissions": {
    "additionalDirectories": ["/custom/path"]
  }
}

Troubleshooting

Ruby version mismatch

If you see "Your Ruby version is X, but your Gemfile specified 3.3.10":

rbenv install 3.3.10
rbenv local 3.3.10

Bundler issues

If gems fail to install:

gem install bundler
bundle config set --local path 'vendor/bundle'
bundle install

Permission errors

Ensure the bin/raictl is executable:

chmod +x bin/raictl

Updating Dependencies

Gemfile.lock is tracked in git and CI uses frozen mode (see ADR-008). Always commit lockfile changes explicitly.

To update a specific gem:

bundle update <gem-name>
bundle exec rspec                 # verify tests pass
bundle exec rubocop               # verify no new offenses
bundle exec bundler-audit check   # verify no CVEs
git add Gemfile.lock
git commit -m "chore(deps): update <gem-name> to X.Y.Z"

To update all dependencies:

bundle update
bundle exec rspec && bundle exec rubocop
bundle exec bundler-audit check
git add Gemfile.lock
git commit -m "chore(deps): update all dependencies"

Uninstalling

To remove the project while preserving Claude Code data:

# Remove only the rosett-ai-related files
rm -rf bin/ lib/ spec/ doc/ conf/
rm -f Gemfile Gemfile.lock rosett-ai.gemspec Rakefile
rm -f .ruby-version .rubocop.yml .reek.yml .rspec
rm -f .overcommit.yml .gitleaks.toml
rm -rf .gitlab-ci-files/ .gitlab-ci.yml
rm -rf .git/