jules-ruby 0.0.67

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b8c57f38a3d3f7419ad7bd5a6a1f2690ba72b0106ccbe01ce4cdf28b115af7d
+  data.tar.gz: 04cd808849c6993f215fd99a697e7b02553c3616ce308782881365c21f6f2026
+SHA512:
+  metadata.gz: bd7a74a418c3fbaaf2b5118433ec6268dd4da3bd1485dfd066193c380953f742a9e1ef00067f6d29acdc0146ab43ce12d7495ca3676222d027ccd5cdbc667bb8
+  data.tar.gz: 31d50df4687c9fbfef15cab8299f3997cab960f5a5286f7bacd5db0e6094f7a42833747e14f23f1c4a70716e9c3821e114a1528842108889c4323666f78acca8

data/.jules/bolt.md

@@ -0,0 +1,4 @@
+## 2025-10-18 - Async::HTTP::Internet Usage
+
+**Learning:** `Async::HTTP::Internet.new` is instantiated for every request in `JulesRuby::Client#request`, which likely prevents connection keep-alive/pooling.
+**Action:** A significant future optimization would be to reuse the `Async::HTTP::Internet` instance, but this requires careful management of the `Async` reactor lifecycle since the current implementation wraps each request in its own `Async { ... }.wait` block.

data/.rubocop.yml

@@ -0,0 +1,51 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'Gemfile'
+    - 'Rakefile'
+    - '*.gemspec'
+    - 'test-jules-ruby.rb'
+    - 'lib/jules-ruby/cli/banner.rb'
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ClassLength:
+  Max: 150
+  Exclude:
+    - 'lib/jules-ruby/cli/sessions.rb'
+    - 'lib/jules-ruby/cli/interactive/session_manager.rb'
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Naming/FileName:
+  Exclude:
+    - 'lib/jules-ruby.rb'
+
+Style/OptionalBooleanParameter:
+  Exclude:
+    - 'lib/jules-ruby/cli.rb'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/jules-ruby/cli/prompts.rb'

data/AGENTS.md

@@ -0,0 +1,250 @@
+# AI Agent Guide for jules-ruby
+
+This document helps AI coding agents understand the codebase structure, conventions, and common commands.
+
+## Project Overview
+
+**jules-ruby** is a Ruby gem providing a client for the [Jules API](https://developers.google.com/jules/api) to programmatically create and manage asynchronous coding tasks. It includes both a Ruby library and a CLI with interactive TUI mode.
+
+## Project Structure
+
+```
+jules-ruby/
+├── lib/
+│   ├── jules-ruby.rb              # Main entry point, requires all modules
+│   └── jules-ruby/
+│       ├── client.rb              # HTTP client with async-http
+│       ├── configuration.rb       # Global config (api_key, timeout)
+│       ├── errors.rb              # Custom error classes
+│       ├── version.rb             # Gem version
+│       ├── cli.rb                 # Thor-based CLI commands
+│       ├── cli/
+│       │   ├── banner.rb          # CLI banner/logo display
+│       │   ├── interactive.rb     # Interactive TUI mode (TTY::Prompt)
+│       │   └── prompts.rb         # Shared prompt helpers
+│       ├── models/                # Data objects returned from API
+│       │   ├── activity.rb
+│       │   ├── artifact.rb
+│       │   ├── github_repo.rb
+│       │   ├── github_branch.rb
+│       │   ├── plan.rb
+│       │   ├── plan_step.rb
+│       │   ├── pull_request.rb
+│       │   ├── session.rb
+│       │   ├── source.rb
+│       │   └── source_context.rb
+│       └── resources/             # API resource classes
+│           ├── base.rb            # Base resource with HTTP methods
+│           ├── activities.rb
+│           ├── sessions.rb
+│           └── sources.rb
+├── bin/
+│   └── jules-ruby                 # CLI executable
+├── spec/                          # RSpec tests
+└── .env                           # API key configuration (JULES_API_KEY)
+```
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Fix lint issues automatically
+bundle exec rubocop -a
+
+# Build the gem
+gem build jules-ruby.gemspec
+
+# Install locally
+gem install ./jules-ruby-*.gem
+```
+
+## Environment Setup (Already setup on Jules)
+
+These commands were already run on Jules to prepare the environment:
+
+```bash
+#!/bin/bash
+set -e  # Exit immediately if a command exits with a non-zero status
+
+# 1. System Packages: Check individually before apt update/install
+# We gather missing packages first to avoid running apt update unnecessarily
+REQUIRED_PKGS="curl libssl-dev libyaml-dev zlib1g-dev libreadline-dev libgdbm-dev"
+MISSING_PKGS=""
+
+for pkg in $REQUIRED_PKGS; do
+    if ! dpkg -s "$pkg" >/dev/null 2>&1; then
+        MISSING_PKGS="$MISSING_PKGS $pkg"
+    fi
+done
+if [ -n "$MISSING_PKGS" ]; then
+    echo "Installing missing packages: $MISSING_PKGS"
+    sudo apt-get update -y
+    sudo apt-get install -y $MISSING_PKGS
+else
+    echo "System packages already installed."
+fi
+
+# 2. Install Mise: Check for the binary
+if [ ! -f "$HOME/.local/bin/mise" ]; then
+    echo "Installing mise..."
+    curl https://mise.run | sh
+else
+    echo "mise already installed."
+fi
+
+# Set path for the duration of this script
+export PATH="$HOME/.local/bin:$PATH"
+
+# 3. Activate Mise: Always run this to ensure the current shell has access to tools
+eval "$(mise activate bash --shims)"
+
+# 4. Mise Tools: 'mise install' is generally smart, but we can skip if you want pure speed.
+# However, keep it to ensure version compliance.
+mise trust -a
+mise install
+
+# 5. Global Gems: Check if they exist
+if ! gem list -i bundler >/dev/null 2>&1; then
+    gem install --quiet bundler
+fi
+
+if ! gem list -i rake >/dev/null 2>&1; then
+    gem install --quiet rake
+fi
+
+echo "Done with Ruby install!"
+
+# 6. Bundle Install: Use 'bundle check' to skip 'bundle install'
+if ! bundle check >/dev/null 2>&1; then
+    echo "Installing project dependencies..."
+    bundle install
+else
+    echo "Bundle dependencies satisfied."
+fi
+
+echo
+echo "Environment prepared!"
+```
+
+## Code Style Guidelines
+
+### Ruby Version
+- Target Ruby 3.0+ (`required_ruby_version >= 3.0.0`)
+
+### RuboCop Configuration
+Key settings from `.rubocop.yml`:
+- **Line length**: Max 120 characters
+- **Method length**: Max 20 lines
+- **Class length**: Max 150 lines
+- **ABC size**: Max 25
+- **Cyclomatic complexity**: Max 10
+- Documentation cop is disabled
+
+### Naming Conventions
+- **Module**: `JulesRuby` (camelCase)
+- **Gem name**: `jules-ruby` (hyphenated, matching file paths)
+- **Files**: Hyphenated to match gem name (`jules-ruby/` directory)
+
+### Architecture Patterns
+
+1. **Models** (`lib/jules-ruby/models/`): Plain Ruby objects with:
+   - `initialize(attributes = {})` accepting a hash
+   - Attribute readers for all fields
+   - Convenience methods for state checking (e.g., `session.completed?`)
+   - `from_api_response(data)` class method for parsing API responses
+
+2. **Resources** (`lib/jules-ruby/resources/`): API endpoint wrappers extending `Base`:
+   - `list(params)` - Returns `{ resource_name: [], next_page_token: nil }`
+   - `find(id)` - Returns single model instance
+   - `all(params)` - Fetches all pages, returns array
+   - `create(params)` - For writable resources
+
+3. **Client** (`lib/jules-ruby/client.rb`): Entry point providing:
+   - `client.sources`, `client.sessions`, `client.activities` resource accessors
+   - Uses `async-http` for HTTP requests
+   - Handles authentication via `Authorization: Bearer` header
+
+4. **CLI** (`lib/jules-ruby/cli.rb`): Thor-based commands:
+   - Subcommands: `sources`, `sessions`, `activities`, `interactive`
+   - Output formats: `--format=table` (default) or `--format=json`
+
+### CLI Color Theme
+
+The interactive CLI uses a custom purple color theme defined in `lib/jules-ruby/cli/prompts.rb`:
+
+```ruby
+COLORS = {
+  purple: [147, 112, 219],   # #9370DB - menu items, values, content
+  lavender: [196, 181, 253], # #C4B5FD - labels, prompts  
+  muted: [139, 92, 246],     # #8B5CF6 - dividers, decorations
+  dim: [107, 114, 128]       # #6B7280 - hints like "Press any key..."
+}.freeze
+```
+
+**Color helpers** (in `Prompts` module):
+- `rgb_color(text, :color_name)` - Apply true-color ANSI escape sequences
+- `highlight(text)` - Apply lavender color
+- `muted(text)` - Apply dim color
+- `divider` - Return a colored divider line
+
+**When modifying CLI output**, use these helpers instead of raw strings to maintain the theme. The banner uses a separate HSL-based gradient in `banner.rb`.
+
+## Dependencies
+
+### Runtime
+- `async-http ~> 0.75` - Async HTTP client
+- `dotenv ~> 3.0` - Environment variable loading
+- `thor ~> 1.3` - CLI framework
+- `tty-prompt ~> 0.23` - Interactive prompts
+- `tty-spinner ~> 0.9` - Loading spinners
+- `pastel ~> 0.8` - Terminal output styling
+
+### Development
+- `rspec ~> 3.0` - Testing
+- `webmock ~> 3.0` - HTTP request stubbing
+- `rubocop ~> 1.0` - Linting
+- `simplecov ~> 0.22` - Code coverage
+
+## Configuration
+
+The gem uses `JULES_API_KEY` from environment or `.env` file:
+
+```ruby
+# Option 1: Environment variable
+ENV['JULES_API_KEY'] = 'your_key'
+
+# Option 2: Block configuration
+JulesRuby.configure do |config|
+  config.api_key = 'your_key'
+  config.timeout = 60
+end
+
+# Option 3: Per-client
+client = JulesRuby::Client.new(api_key: 'your_key')
+```
+
+## Error Handling
+
+Custom errors in `lib/jules-ruby/errors.rb`:
+- `JulesRuby::Error` - Base error class
+- `JulesRuby::AuthenticationError` - 401/403 responses
+- `JulesRuby::NotFoundError` - 404 responses
+- `JulesRuby::RateLimitError` - 429 responses
+- `JulesRuby::ServerError` - 5xx responses
+
+## API Reference
+
+The gem wraps the Jules API documented at: https://developers.google.com/jules/api
+
+Main resources:
+- **Sources**: Connected GitHub repositories
+- **Sessions**: Coding task sessions (create, approve plans, send messages)
+- **Activities**: Session events/history (messages, plans, progress updates)

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.67] - 2025-12-17
+
+### Added
+- CLI with commands for sources, sessions, and activities
+- Interactive TUI mode (`jules-ruby interactive`)
+- JSON output format (`--format=json`)
+- Ruby client library for Jules API
+- Session management (create, approve, message, delete)
+- Activity monitoring with pagination
+- Source repository listing
+
+### Changed
+- Initial public release

data/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to Jules Ruby
+
+Thank you for your interest in contributing to jules-ruby!
+
+## Development Setup
+
+1. Fork and clone the repository:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/jules-ruby.git
+   cd jules-ruby
+   ```
+
+2. Install dependencies:
+   ```bash
+   bundle install
+   ```
+
+3. Set up your API key for testing:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your Jules API key
+   ```
+
+## Running Tests
+
+```bash
+# Run the test suite
+bundle exec rspec
+
+# Run with coverage report
+COVERAGE=true bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+```
+
+## Making Changes
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes and ensure:
+   - All tests pass (`bundle exec rspec`)
+   - Code follows style guidelines (`bundle exec rubocop`)
+   - New code has test coverage
+
+3. Commit with a clear message:
+   ```bash
+   git commit -m "Add feature: brief description"
+   ```
+
+4. Push and open a Pull Request
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single change
+- Update documentation if adding new features
+- Add tests for new functionality
+- Update CHANGELOG.md under "Unreleased" section
+
+## Release Process (Maintainers)
+
+1. Update version in `jules-ruby.gemspec`
+2. Update `CHANGELOG.md` with release notes
+3. Commit: `git commit -am "Bump version to X.Y.Z"`
+4. Tag: `git tag vX.Y.Z`
+5. Push: `git push origin main --tags`
+
+The GitHub Actions release workflow will automatically:
+- Build the gem
+- Generate checksums
+- Publish to RubyGems.org
+- Create a GitHub Release
+
+## Code of Conduct
+
+Be kind and respectful. We're all here to learn and build together.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taylor Weibley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.