linear-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 95f692f69f9d45f3b6f37dc1fa41a8f5312814eabb13ebfb6ed93828a7748699
+  data.tar.gz: 4176ed98a5f0b85cc30677622215ce39e1a1d0a4251dd5c88e61c67eb4d2df77
+SHA512:
+  metadata.gz: e3b1154891eab716f95223b77a867b1a21ada9c7336a841027db055253febc21262797a7bf17c1b7cf10ca0f9c6784d212b6b85bf81e2c3b8dcf67e794b6c27b
+  data.tar.gz: 738eefde06923665d76b822818f93b5d1fe0c6e0dc30232c940d5fa73b2d1e4deb4010b3ea1eb0ee8115772b12e1d90dbb14fe36ac5d015121d051b447a3f05a

data/bin/linear

@@ -0,0 +1,132 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/linear'
+require 'optparse'
+
+def show_usage
+  puts <<~USAGE
+    Linear CLI - Ruby wrapper for Linear GraphQL API
+
+    Usage:
+      linear issue ISSUE_ID                   Fetch issue details
+      linear search QUERY [OPTIONS]           Search for issues
+      linear mine                             Show issues assigned to you
+      linear teams                            List all teams
+      linear comment ISSUE_ID COMMENT         Add a comment to an issue
+      linear update ISSUE_ID STATE            Update issue state
+
+    Search Options:
+      --team TEAM_KEY                   Filter by team key
+      --state STATE                     Filter by state name
+
+    Examples:
+      linear issue ENG-123
+      linear search "bug fix" --team=ENG --state=Backlog
+      linear mine
+      linear comment FAT-85 "This is done"
+      linear update FAT-85 "Done"
+
+    Configuration:
+      Set the LINEAR_API_KEY environment variable with your API key from:
+      https://linear.app/settings/api
+  USAGE
+end
+
+command = ARGV.shift
+
+case command
+when 'issue'
+  issue_id = ARGV.shift
+  if issue_id.nil? || issue_id.empty?
+    puts "Error: issue ID required"
+    puts "Usage: linear issue ISSUE_ID"
+    exit 1
+  end
+
+  begin
+    Linear::Commands.fetch_issue(issue_id)
+  rescue => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+when 'search'
+  query = ARGV.shift
+  if query.nil? || query.empty?
+    puts "Error: search query required"
+    puts "Usage: linear search QUERY [--team TEAM] [--state STATE]"
+    exit 1
+  end
+
+  options = {}
+  OptionParser.new do |opts|
+    opts.on("--team TEAM", "Filter by team key") { |v| options[:team] = v }
+    opts.on("--state STATE", "Filter by state name") { |v| options[:state] = v }
+  end.parse!
+
+  begin
+    Linear::Commands.search(query, options)
+  rescue => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+when 'mine'
+  begin
+    Linear::Commands.my_issues
+  rescue => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+when 'teams'
+  begin
+    Linear::Commands.list_teams
+  rescue => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+when 'comment'
+  issue_id = ARGV.shift
+  comment_body = ARGV.shift
+
+  if issue_id.nil? || issue_id.empty? || comment_body.nil? || comment_body.empty?
+    puts "Error: issue ID and comment text required"
+    puts "Usage: linear comment ISSUE_ID \"comment text\""
+    exit 1
+  end
+
+  begin
+    Linear::Commands.add_comment(issue_id, comment_body)
+  rescue => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+when 'update'
+  issue_id = ARGV.shift
+  state_name = ARGV.shift
+
+  if issue_id.nil? || issue_id.empty? || state_name.nil? || state_name.empty?
+    puts "Error: issue ID and state name required"
+    puts "Usage: linear update ISSUE_ID \"State Name\""
+    exit 1
+  end
+
+  begin
+    Linear::Commands.update_issue_state(issue_id, state_name)
+  rescue => e
+    puts "Error: #{e.message}"
+    exit 1
+  end
+
+when 'help', '--help', '-h', nil
+  show_usage
+
+else
+  puts "Unknown command: #{command}"
+  puts ""
+  show_usage
+  exit 1
+end

data/lib/linear/client.rb

@@ -0,0 +1,31 @@
+require 'json'
+require 'shellwords'
+
+module Linear
+  class Client
+    BASE_URL = "https://api.linear.app/graphql"
+
+    def initialize(api_key = nil)
+      @api_key = api_key || ENV['LINEAR_API_KEY']
+      raise "No API key configured. Set LINEAR_API_KEY environment variable" unless @api_key
+    end
+
+    def query(graphql_query, variables = {})
+      payload = { query: graphql_query, variables: variables }.to_json
+      escaped_payload = Shellwords.escape(payload)
+
+      result = `curl -s -X POST #{BASE_URL} \
+        -H "Content-Type: application/json" \
+        -H "Authorization: #{@api_key}" \
+        -d #{escaped_payload}`
+
+      parsed = JSON.parse(result)
+
+      if parsed["errors"]
+        raise "GraphQL Error: #{parsed["errors"].map { |e| e["message"] }.join(", ")}"
+      end
+
+      parsed
+    end
+  end
+end

data/lib/linear/commands.rb

@@ -0,0 +1,182 @@
+module Linear
+  module Commands
+    extend self
+
+    def fetch_issue(issue_id, client: Client.new)
+      result = client.query(Queries::ISSUE, { id: issue_id })
+
+      issue = result.dig("data", "issue")
+      if issue
+        display_issue(issue)
+      else
+        puts "Issue not found: #{issue_id}"
+      end
+    end
+
+    def search(query, options = {}, client: Client.new)
+      filter = { title: { contains: query } }
+      filter[:team] = { key: { eq: options[:team] } } if options[:team]
+      filter[:state] = { name: { eq: options[:state] } } if options[:state]
+
+      result = client.query(Queries::SEARCH_ISSUES, { filter: filter })
+
+      issues = result.dig("data", "issues", "nodes") || []
+      if issues.empty?
+        puts "No issues found matching: #{query}"
+      else
+        display_issue_list(issues)
+      end
+    end
+
+    def my_issues(client: Client.new)
+      result = client.query(Queries::MY_ISSUES)
+
+      issues = result.dig("data", "viewer", "assignedIssues", "nodes") || []
+      if issues.empty?
+        puts "No issues assigned to you"
+      else
+        display_issue_list(issues)
+      end
+    end
+
+    def list_teams(client: Client.new)
+      result = client.query(Queries::TEAMS)
+
+      teams = result.dig("data", "teams", "nodes") || []
+      teams.each do |team|
+        puts "#{team['key'].ljust(10)} #{team['name']}"
+      end
+    end
+
+    def add_comment(issue_id, body, client: Client.new)
+      # First get the issue to get its internal ID
+      issue_result = client.query(Queries::ISSUE, { id: issue_id })
+      issue = issue_result.dig("data", "issue")
+
+      unless issue
+        puts "Error: Issue not found: #{issue_id}"
+        return
+      end
+
+      result = client.query(Queries::CREATE_COMMENT, {
+        issueId: issue['id'],
+        body: body
+      })
+
+      if result.dig("data", "commentCreate", "success")
+        puts "Comment added to #{issue_id}"
+      else
+        puts "Error: Failed to add comment"
+      end
+    end
+
+    def update_issue_state(issue_id, state_name, client: Client.new)
+      # Get the issue details including team
+      issue_result = client.query(Queries::ISSUE, { id: issue_id })
+      issue = issue_result.dig("data", "issue")
+
+      unless issue
+        puts "Error: Issue not found: #{issue_id}"
+        return
+      end
+
+      # Get team states - need to find team ID first
+      teams_result = client.query(Queries::TEAMS)
+      teams = teams_result.dig("data", "teams", "nodes") || []
+
+      # Find the team from the issue identifier prefix (e.g., "FAT" from "FAT-85")
+      team_key = issue_id.split('-').first
+      team = teams.find { |t| t['key'] == team_key }
+
+      unless team
+        puts "Error: Team not found for issue #{issue_id}"
+        return
+      end
+
+      # Get workflow states for the team
+      states_result = client.query(Queries::WORKFLOW_STATES, { teamId: team['id'] })
+      states = states_result.dig("data", "team", "states", "nodes") || []
+
+      # Find the state by name (case-insensitive)
+      target_state = states.find { |s| s['name'].downcase == state_name.downcase }
+
+      unless target_state
+        puts "Error: State '#{state_name}' not found. Available states:"
+        states.each { |s| puts "  - #{s['name']}" }
+        return
+      end
+
+      # Update the issue
+      result = client.query(Queries::UPDATE_ISSUE, {
+        issueId: issue['id'],
+        stateId: target_state['id']
+      })
+
+      if result.dig("data", "issueUpdate", "success")
+        puts "Updated #{issue_id} to '#{target_state['name']}'"
+      else
+        puts "Error: Failed to update issue state"
+      end
+    end
+
+    def update_issue_description(issue_id, description, client: Client.new)
+      # Get the issue to get its internal ID
+      issue_result = client.query(Queries::ISSUE, { id: issue_id })
+      issue = issue_result.dig("data", "issue")
+
+      unless issue
+        puts "Error: Issue not found: #{issue_id}"
+        return
+      end
+
+      # Update the issue description
+      result = client.query(Queries::UPDATE_ISSUE, {
+        issueId: issue['id'],
+        description: description
+      })
+
+      if result.dig("data", "issueUpdate", "success")
+        puts "Updated #{issue_id} description"
+      else
+        puts "Error: Failed to update issue description"
+      end
+    end
+
+    private
+
+    def display_issue(issue)
+      puts "\n#{issue['identifier']}: #{issue['title']}"
+      puts "=" * 60
+      puts "Status:   #{issue['state']['name']}"
+      puts "Assignee: #{issue.dig('assignee', 'name') || 'Unassigned'}"
+      puts "Priority: #{priority_label(issue['priority'])}"
+      puts "URL:      #{issue['url']}"
+      puts "\nDescription:"
+      puts issue['description'] || "(no description)"
+      puts ""
+    end
+
+    def display_issue_list(issues)
+      puts "\nFound #{issues.length} issue(s):\n\n"
+      issues.each do |issue|
+        state_badge = "[#{issue['state']['name']}]".ljust(15)
+        priority_badge = priority_label(issue['priority']).ljust(8)
+        assignee = (issue.dig('assignee', 'name') || 'Unassigned').ljust(15)
+
+        puts "#{issue['identifier'].ljust(12)} #{state_badge} #{priority_badge} #{assignee} #{issue['title']}"
+      end
+      puts ""
+    end
+
+    def priority_label(priority)
+      case priority
+      when 0 then "None"
+      when 1 then "Urgent"
+      when 2 then "High"
+      when 3 then "Medium"
+      when 4 then "Low"
+      else "Unknown"
+      end
+    end
+  end
+end

data/lib/linear/queries.rb

@@ -0,0 +1,127 @@
+module Linear
+  module Queries
+    ISSUE = <<~GQL
+      query($id: String!) {
+        issue(id: $id) {
+          id
+          identifier
+          title
+          description
+          state {
+            name
+            type
+          }
+          assignee {
+            name
+            email
+          }
+          priority
+          createdAt
+          updatedAt
+          url
+        }
+      }
+    GQL
+
+    SEARCH_ISSUES = <<~GQL
+      query($filter: IssueFilter!) {
+        issues(filter: $filter) {
+          nodes {
+            id
+            identifier
+            title
+            state {
+              name
+              type
+            }
+            assignee {
+              name
+            }
+            priority
+            url
+          }
+        }
+      }
+    GQL
+
+    MY_ISSUES = <<~GQL
+      query {
+        viewer {
+          assignedIssues {
+            nodes {
+              id
+              identifier
+              title
+              state {
+                name
+                type
+              }
+              priority
+              url
+            }
+          }
+        }
+      }
+    GQL
+
+    TEAMS = <<~GQL
+      query {
+        teams {
+          nodes {
+            id
+            key
+            name
+          }
+        }
+      }
+    GQL
+
+    WORKFLOW_STATES = <<~GQL
+      query($teamId: String!) {
+        team(id: $teamId) {
+          states {
+            nodes {
+              id
+              name
+              type
+            }
+          }
+        }
+      }
+    GQL
+
+    CREATE_COMMENT = <<~GQL
+      mutation($issueId: String!, $body: String!) {
+        commentCreate(input: {
+          issueId: $issueId
+          body: $body
+        }) {
+          success
+          comment {
+            id
+            body
+          }
+        }
+      }
+    GQL
+
+    UPDATE_ISSUE = <<~GQL
+      mutation($issueId: String!, $stateId: String, $description: String) {
+        issueUpdate(id: $issueId, input: {
+          stateId: $stateId
+          description: $description
+        }) {
+          success
+          issue {
+            id
+            identifier
+            state {
+              name
+            }
+            description
+          }
+        }
+      }
+    GQL
+  end
+end

data/lib/linear/version.rb

@@ -0,0 +1,3 @@
+module Linear
+  VERSION = "0.1.0"
+end

data/lib/linear.rb

@@ -0,0 +1,7 @@
+require_relative "linear/version"
+require_relative "linear/client"
+require_relative "linear/queries"
+require_relative "linear/commands"
+
+module Linear
+end

data/readme.md

@@ -0,0 +1,162 @@
+# linear-rb
+
+A lightweight Ruby CLI wrapper for the Linear GraphQL API. Built for efficiency with zero external dependencies.
+
+## Installation
+
+### As a gem
+
+```bash
+gem install linear-rb
+```
+
+### Direct usage (without installing)
+
+```bash
+./bin/linear <command>
+```
+
+## Configuration
+
+Set your Linear API key as an environment variable:
+
+```bash
+export LINEAR_API_KEY=lin_api_YOUR_KEY_HERE
+```
+
+Or prepend each command:
+
+```bash
+ LINEAR_API_KEY=XYZ123 linear projects
+```
+
+Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to make it permanent.
+
+Get your API key from: https://linear.app/settings/api
+
+**Security Note**: The gem never stores your API key - it only reads from the environment variable.
+
+## Usage
+
+### View issue details
+
+```bash
+linear issue ENG-123
+```
+
+### Search for issues
+
+```bash
+# Basic search
+linear search "authentication bug"
+
+# Filter by team
+linear search "bug" --team=ENG
+
+# Filter by state
+linear search "feature" --state=Backlog
+
+# Combine filters
+linear search "api" --team=ENG --state="In Progress"
+```
+
+### View your assigned issues
+
+```bash
+linear mine
+```
+
+### List teams
+
+```bash
+linear teams
+```
+
+### Add a comment to an issue
+
+```bash
+linear comment DEV-85 "This looks good to me"
+```
+
+### Update issue state
+
+```bash
+# Move issue to a different state
+linear update DEV-85 "Done"
+linear update ENG-123 "In Progress"
+```
+
+### Help
+
+```bash
+linear help
+```
+
+## As a Library
+
+You can also use linear-rb as a library in your Ruby code:
+
+```ruby
+require 'linear'
+
+# Option 1: Use LINEAR_API_KEY environment variable
+# (No code needed - just set the env var)
+
+# Option 2: Pass API key directly to client
+client = Linear::Client.new('lin_api_xxx')
+
+# Use the client directly
+client = Linear::Client.new
+result = client.query(Linear::Queries::ISSUE, { id: "ENG-123" })
+
+# Or use commands
+Linear::Commands.fetch_issue("ENG-123")
+Linear::Commands.search("bug", team: "ENG")
+Linear::Commands.my_issues
+Linear::Commands.add_comment("DEV-85", "Great work!")
+Linear::Commands.update_issue_state("ENG-85", "Done")
+Linear::Commands.update_issue_description("MKT-85", "Updated description")
+```
+
+
+## Development
+
+```bash
+# Run locally
+./bin/linear help
+
+# Build gem
+gem build linear-rb.gemspec
+
+# Install locally
+gem install linear-rb-0.1.0.gem
+```
+
+### Testing
+
+The project includes both unit tests and integration tests:
+
+```bash
+# Run all tests (skips live API tests by default)
+rspec
+
+# Run tests with live API integration
+LINEAR_API_KEY=your_key rspec
+
+# Run only integration tests
+rspec spec/integration/
+
+# Run specific test file
+rspec spec/linear/client_spec.rb
+```
+
+**Test Structure:**
+- `spec/linear/` - Unit tests with mocked API responses
+- `spec/integration/` - Integration tests for the CLI binary
+  - Tests tagged with `:live` require a valid `LINEAR_API_KEY` and will make real API calls
+  - Live tests display command output and intent rather than making assertions
+  - Useful for verifying the CLI works end-to-end with real Linear data
+
+## License
+
+MIT

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: linear-rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dave Kinkead
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Efficient command-line interface for interacting with Linear's GraphQL
+  API
+email:
+- hi@davekinkead.com
+executables:
+- linear
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/linear
+- lib/linear.rb
+- lib/linear/client.rb
+- lib/linear/commands.rb
+- lib/linear/queries.rb
+- lib/linear/version.rb
+- readme.md
+homepage: https://github.com/davekinkead/linear-rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby CLI wrapper for Linear GraphQL API
+test_files: []