jules-ruby 0.0.67

data/README.md

@@ -0,0 +1,330 @@
+# Jules Ruby
+
+<p align="center">
+  <img src="assets/banner.png" alt="Jules Ruby" width="600">
+</p>
+
+[![Gem Version](https://badge.fury.io/rb/jules-ruby.svg)](https://badge.fury.io/rb/jules-ruby)
+[![CI](https://github.com/tweibley/jules-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/tweibley/jules-ruby/actions/workflows/ci.yml)
+
+A Ruby gem for interacting with the [Jules API](https://developers.google.com/jules/api) to programmatically create and manage asynchronous coding tasks.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'jules-ruby'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself:
+
+```bash
+gem install jules-ruby
+```
+
+## Configuration
+
+### Using environment variables (recommended)
+
+Create a `.env` file in your project root:
+
+```
+JULES_API_KEY=your_api_key_here
+```
+
+The gem automatically loads from `.env` using dotenv.
+
+### Using Ruby configuration
+
+```ruby
+require 'jules-ruby'
+
+JulesRuby.configure do |config|
+  config.api_key = 'your_api_key_here'
+  config.timeout = 60 # optional, default is 30 seconds
+end
+```
+
+### Per-client configuration
+
+```ruby
+client = JulesRuby::Client.new(api_key: 'different_api_key')
+```
+
+## Command-Line Interface
+
+The gem includes a CLI for interacting with the Jules API from your terminal.
+
+### Installation
+
+After installing the gem, the `jules-ruby` command becomes available:
+
+```bash
+jules-ruby help
+```
+
+### Commands
+
+#### Sources
+
+```bash
+# List all connected repositories
+jules-ruby sources list
+jules-ruby sources list --format=json
+
+# Show source details
+jules-ruby sources show sources/github/owner/repo
+```
+
+#### Sessions
+
+```bash
+# List all sessions
+jules-ruby sessions list
+jules-ruby sessions list --format=json
+
+# Show session details
+jules-ruby sessions show <session_id>
+
+# Create a new session
+jules-ruby sessions create \
+  --source=sources/github/owner/repo \
+  --branch=main \
+  --prompt="Fix the login bug" \
+  --title="Fix Login" \
+  --auto-pr
+
+# Approve a plan
+jules-ruby sessions approve <session_id>
+
+# Send a message
+jules-ruby sessions message <session_id> --prompt="Also add unit tests"
+
+# Delete a session
+jules-ruby sessions delete <session_id>
+```
+
+#### Activities
+
+```bash
+# List activities for a session
+jules-ruby activities list <session_id>
+jules-ruby activities list <session_id> --format=json
+
+# Show activity details
+jules-ruby activities show sessions/<session_id>/activities/<activity_id>
+```
+
+### Interactive Mode
+
+Start the interactive TUI for guided workflows:
+
+```bash
+jules-ruby interactive
+# or
+jules-ruby -i
+```
+
+Interactive mode provides:
+- **Main menu** - Navigate between actions
+- **Session wizard** - Step-by-step session creation with source selection
+- **Session viewer** - View details, approve plans, send messages, delete
+- **Activities viewer** - See session progress and history
+
+### Output Formats
+
+All list commands support `--format=table` (default) or `--format=json`.
+
+### Gemini CLI Extension
+
+Use jules-ruby directly from [Gemini CLI](https://github.com/google-gemini/gemini-cli) with our extension:
+
+👉 [jules-ruby-gemini-cli-extension](https://github.com/tweibley/jules-ruby-gemini-cli-extension)
+
+## Usage
+
+### Initialize the client
+
+```ruby
+require 'jules-ruby'
+
+client = JulesRuby::Client.new
+```
+
+### Sources
+
+List your connected repositories:
+
+```ruby
+# List sources with pagination
+result = client.sources.list(page_size: 10)
+result[:sources].each do |source|
+  puts "#{source.name}: #{source.github_repo.full_name}"
+end
+
+# Get all sources
+sources = client.sources.all
+```
+
+### Sessions
+
+Create and manage coding sessions:
+
+```ruby
+# Create a new session
+session = client.sessions.create(
+  prompt: "Fix the login bug in the authentication module",
+  source_context: {
+    "source" => "sources/github/myorg/myrepo",
+    "githubRepoContext" => { "startingBranch" => "main" }
+  },
+  title: "Fix Login Bug",
+  automation_mode: "AUTO_CREATE_PR"  # optional: auto-create PR when done
+)
+
+puts "Session created: #{session.url}"
+puts "State: #{session.state}"
+
+# List sessions
+result = client.sessions.list(page_size: 10)
+result[:sessions].each { |s| puts "#{s.title}: #{s.state}" }
+
+# Get a specific session
+session = client.sessions.find("12345678")
+# or
+session = client.sessions.find("sessions/12345678")
+
+# Check session state
+if session.awaiting_plan_approval?
+  client.sessions.approve_plan(session.name)
+end
+
+# Send a message to the agent
+client.sessions.send_message(session.name, prompt: "Can you also add unit tests?")
+
+# Delete a session
+client.sessions.destroy(session.name)
+```
+
+### Activities
+
+Monitor session progress:
+
+```ruby
+# List activities for a session
+result = client.activities.list(session.name, page_size: 30)
+
+result[:activities].each do |activity|
+  case activity.type
+  when :plan_generated
+    puts "Plan: #{activity.plan.steps.map(&:title).join(', ')}"
+  when :progress_updated
+    puts "Progress: #{activity.progress_title}"
+  when :session_completed
+    puts "Session completed!"
+  when :session_failed
+    puts "Failed: #{activity.failure_reason}"
+  end
+end
+
+# Get all activities
+activities = client.activities.all(session.name)
+```
+
+### Working with models
+
+#### Session states
+
+```ruby
+session.queued?                 # Waiting to start
+session.planning?               # Creating a plan
+session.awaiting_plan_approval? # Needs plan approval
+session.awaiting_user_feedback? # Waiting for user input
+session.in_progress?            # Working on the task
+session.completed?              # Finished successfully
+session.failed?                 # Failed
+session.active?                 # Any non-terminal state
+```
+
+#### Activity types
+
+```ruby
+activity.agent_message?    # Agent posted a message
+activity.user_message?     # User posted a message
+activity.plan_generated?   # A plan was created
+activity.plan_approved?    # A plan was approved
+activity.progress_update?  # Progress update
+activity.session_completed? # Session completed
+activity.session_failed?   # Session failed
+
+# Get content based on type
+activity.message           # For agent/user messages
+activity.plan              # For plan_generated (returns Plan object)
+activity.progress_title    # For progress updates
+activity.failure_reason    # For session_failed
+```
+
+#### Artifacts
+
+```ruby
+activity.artifacts.each do |artifact|
+  case artifact.type
+  when :change_set
+    puts "Changes to: #{artifact.source}"
+    puts "Commit message: #{artifact.suggested_commit_message}"
+  when :bash_output
+    puts "Command: #{artifact.bash_command}"
+    puts "Output: #{artifact.bash_output_text}"
+    puts "Exit code: #{artifact.bash_exit_code}"
+  when :media
+    puts "Media type: #{artifact.media_mime_type}"
+  end
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.sessions.find("nonexistent")
+rescue JulesRuby::AuthenticationError => e
+  puts "Invalid API key"
+rescue JulesRuby::NotFoundError => e
+  puts "Session not found"
+rescue JulesRuby::RateLimitError => e
+  puts "Rate limit exceeded, try again later"
+rescue JulesRuby::ServerError => e
+  puts "Server error: #{e.message}"
+rescue JulesRuby::Error => e
+  puts "API error: #{e.message} (status: #{e.status_code})"
+end
+```
+
+## Requirements
+
+- Ruby 3.0+
+- async-http gem
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+namespace :release do
+  desc 'Bump patch version, commit, tag, and push'
+  task :patch do
+    bump_version(:patch)
+  end
+
+  desc 'Bump minor version, commit, tag, and push'
+  task :minor do
+    bump_version(:minor)
+  end
+
+  desc 'Bump major version, commit, tag, and push'
+  task :major do
+    bump_version(:major)
+  end
+end
+
+def bump_version(type)
+  gemspec_file = 'jules-ruby.gemspec'
+  content = File.read(gemspec_file)
+
+  # Extract current version
+  version_match = content.match(/spec\.version\s*=\s*["'](\d+)\.(\d+)\.(\d+)["']/)
+  unless version_match
+    puts 'Could not find version in gemspec'
+    exit 1
+  end
+
+  major, minor, patch = version_match[1..3].map(&:to_i)
+
+  # Bump version based on type
+  case type
+  when :major
+    major += 1
+    minor = 0
+    patch = 0
+  when :minor
+    minor += 1
+    patch = 0
+  when :patch
+    patch += 1
+  end
+
+  new_version = "#{major}.#{minor}.#{patch}"
+  puts "Bumping version to #{new_version}"
+
+  # Update gemspec
+  new_content = content.sub(/spec\.version\s*=\s*["']\d+\.\d+\.\d+["']/, "spec.version       = \"#{new_version}\"")
+  File.write(gemspec_file, new_content)
+
+  # Git operations
+  sh "git add #{gemspec_file}"
+  sh "git commit -m 'Bump version to #{new_version}'"
+  sh "git tag v#{new_version}"
+  sh 'git push origin main'
+  sh "git push origin v#{new_version}"
+
+  puts "Released v#{new_version}!"
+end

data/SECURITY.md

@@ -0,0 +1,41 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.0.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in jules-ruby, please report it responsibly:
+
+1. **Do not** open a public GitHub issue
+2. Email the maintainers at tweibley@gmail.com with:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and work with you to understand and address the issue.
+
+## Security Practices
+
+This gem follows RubyGems security best practices:
+
+- **MFA Required**: All gem owners must have MFA enabled
+- **Trusted Publishing**: Releases use OIDC authentication (no long-lived API keys)
+- **Checksums**: SHA512 checksums are published with each release
+- **Dependency Scanning**: We use `bundle audit` to check for vulnerable dependencies
+
+## Verifying Releases
+
+You can verify the integrity of a release:
+
+```bash
+# Fetch the gem
+gem fetch jules-ruby -v VERSION
+
+# Compare checksum with the one published in GitHub Releases
+ruby -rdigest/sha2 -e "puts Digest::SHA512.hexdigest(File.read('jules-ruby-VERSION.gem'))"
+```

data/bin/jules-ruby

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/jules-ruby'
+require_relative '../lib/jules-ruby/cli'
+
+JulesRuby::CLI.start(ARGV)

data/jules-ruby.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "jules-ruby"
+  spec.version       = "0.0.67"
+  spec.authors       = ["Taylor Weibley"]
+  spec.email         = ["tweibley@gmail.com"]
+
+  spec.summary       = "Ruby CLI for the Jules API"
+  spec.description   = "A Ruby gem for interacting with the Jules API to programmatically create and manage asynchronous coding tasks."
+  spec.homepage      = "https://github.com/tweibley/jules-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "#{spec.homepage}#readme"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[test/ spec/ features/ .git .github Gemfile])
+    end
+  end
+  spec.bindir = "bin"
+  spec.executables = ['jules-ruby']
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "async-http", "~> 0.75"
+  spec.add_dependency "dotenv", "~> 3.0"
+  spec.add_dependency "thor", "~> 1.3"
+  spec.add_dependency "tty-prompt", "~> 0.23"
+  spec.add_dependency "tty-spinner", "~> 0.9"
+  spec.add_dependency "pastel", "~> 0.8"
+
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+end

data/lib/jules-ruby/cli/activities.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module JulesRuby
+  module Commands
+    # Activities subcommand
+    class Activities < Base
+      desc 'list SESSION_ID', 'List activities for a session'
+      long_desc <<~LONGDESC
+        List all activities for a session (messages, plans, progress updates).
+
+        Example:
+          $ jules-ruby activities list SESSION_ID
+      LONGDESC
+      format_option
+      def list(session_id)
+        activities = client.activities.all(session_id)
+        if options[:format] == 'json'
+          puts JSON.pretty_generate(activities.map(&:to_h))
+        else
+          print_activities_table(activities)
+        end
+      rescue JulesRuby::Error => e
+        error_exit(e)
+      end
+
+      desc 'show NAME', 'Show details for an activity'
+      long_desc <<~LONGDESC
+        Show details for a specific activity.
+
+        Example:
+          $ jules-ruby activities show sessions/SESSION_ID/activities/ACTIVITY_ID
+      LONGDESC
+      format_option
+      def show(name)
+        activity = client.activities.find(name)
+        if options[:format] == 'json'
+          puts JSON.pretty_generate(activity.to_h)
+        else
+          print_activity_details(activity)
+        end
+      rescue JulesRuby::Error => e
+        error_exit(e)
+      end
+
+      private
+
+      def print_activities_table(activities)
+        if activities.empty?
+          puts 'No activities found.'
+          return
+        end
+        puts 'ID                   TYPE                 FROM       DESCRIPTION                             '
+        puts '-' * 95
+        activities.each do |a|
+          desc = truncate(activity_summary(a), 38)
+          puts format('%<id>-20s %<type>-20s %<originator>-10s %<desc>-40s',
+                      id: a.id, type: a.type, originator: a.originator || 'N/A', desc: desc)
+        end
+      end
+
+      def print_activity_details(activity)
+        print_activity_header(activity)
+        print_activity_content(activity)
+        print_activity_artifacts(activity.artifacts) if activity.artifacts&.any?
+      end
+
+      def print_activity_header(activity)
+        puts "Name:        #{activity.name}"
+        puts "ID:          #{activity.id}"
+        puts "Type:        #{activity.type}"
+        puts "Originator:  #{activity.originator}"
+        puts "Created:     #{activity.create_time}"
+        puts "Description: #{activity.description}" if activity.description
+      end
+
+      def print_activity_content(activity)
+        case activity.type
+        when :agent_messaged, :user_messaged
+          print_message(activity)
+        when :plan_generated
+          print_plan(activity)
+        when :progress_updated
+          print_progress(activity)
+        when :session_failed
+          puts "\nFailure Reason: #{activity.failure_reason}"
+        end
+      end
+
+      def print_message(activity)
+        puts "\nMessage:"
+        puts "  #{activity.message}"
+      end
+
+      def print_plan(activity)
+        return unless activity.plan
+
+        puts "\nPlan:"
+        activity.plan.steps&.each_with_index do |step, i|
+          puts "  #{i + 1}. #{step.title}"
+        end
+      end
+
+      def print_progress(activity)
+        puts "\nProgress: #{activity.progress_title}"
+        puts "Details:  #{activity.progress_description}" if activity.progress_description
+      end
+
+      def print_activity_artifacts(artifacts)
+        puts "\nArtifacts:"
+        artifacts.each do |artifact|
+          puts "  - Type: #{artifact.type}"
+        end
+      end
+
+      def activity_summary(activity)
+        case activity.type
+        when :agent_messaged, :user_messaged
+          activity.message || ''
+        when :plan_generated
+          "Plan with #{activity.plan&.steps&.length || 0} steps"
+        when :progress_updated
+          activity.progress_title || ''
+        else
+          summary_for_state(activity)
+        end
+      end
+
+      def summary_for_state(activity)
+        case activity.type
+        when :session_completed
+          'Session completed'
+        when :session_failed
+          activity.failure_reason || 'Session failed'
+        else
+          activity.description || ''
+        end
+      end
+    end
+  end
+end