ask-linear 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2cdf635069d34d0554d7e73ff22a0b589627ab59ace75b8376cfff7b11a502d5
+  data.tar.gz: 81cc288e84cb63fb8b622032adbdc911844cbe29097d2b99f5d0a19548fc8f69
+SHA512:
+  metadata.gz: 75e4a052079f42fdb445fcaea78010597c19708a5872a399c970b0f28f72c0ce77a76c0b6df4fe9d2c5681a060cff28cba750fd8de999e6438f745297c7ce87f
+  data.tar.gz: e4e4cb88175a66383b416409f85e05ad2661168f28df182dd82c230429d3ec1b2fef341886f12255a3434af258d74bfc1a40beeff104298f6e4d59b53bbcd631

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+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.

data/README.md

@@ -0,0 +1,157 @@
+# ask-linear
+
+Linear service context for AI agents in the ask-rb ecosystem.
+
+Provides an authenticated GraphQL client, metadata constants for system prompts, and a structured error guide for common Linear API issues.
+
+```ruby
+gem "ask-linear"
+```
+
+## Quick Start
+
+### Get an authenticated client
+
+```ruby
+require "ask-linear"
+
+client = Ask::Linear.client
+
+# List all teams
+result = client.query("query { teams { nodes { id key name } } }")
+
+# Create an issue
+result = client.query(
+  "mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }",
+  { input: { teamId: "TEAM_ID", title: "My issue", description: "Description here" } }
+)
+
+# Fetch a specific issue
+result = client.query(
+  "query($id: String!) { issue(id: $id) { id identifier title description state { name } assignee { name } url } }",
+  { id: "ISSUE_ID" }
+)
+```
+
+The client is a thin wrapper over Faraday that sends GraphQL queries to `https://api.linear.app/graphql`. Wrapped in a proxy that converts `Faraday::UnauthorizedError` (HTTP 401) into `Ask::Auth::InvalidCredential` with actionable error messages.
+
+### Authentication
+
+The client resolves a Linear API key via `Ask::Auth.resolve(:linear_api_key)`. API keys can be provided through any configured auth provider:
+
+1. **Environment variable:** `LINEAR_API_KEY`
+2. **Credentials file:** `~/.ask/credentials.yml`
+3. **Rails credentials:** `Rails.application.credentials.linear_api_key`
+4. **OAuth / Database:** Custom providers
+
+Generate an API key at [linear.app/settings/api](https://linear.app/settings/api).
+
+## Context Constants
+
+Use these constants to build system prompts for AI agents:
+
+| Constant | Value |
+|---|---|
+| `Ask::Linear::DESCRIPTION` | "Linear — issue tracking, project management, roadmaps, sprints" |
+| `Ask::Linear::DOCS_URL` | https://developers.linear.app/docs |
+| `Ask::Linear::GRAPHQL_URL` | https://api.linear.app/graphql |
+| `Ask::Linear::AUTH_NAME` | `:linear_api_key` |
+| `Ask::Linear::AUTH_HOW` | "https://linear.app/settings/api — generate a personal API key" |
+| `Ask::Linear::GEM_NAME` | `"faraday"` |
+| `Ask::Linear::QUICK_START` | Copy-paste Ruby code snippet with common GraphQL operations |
+
+## Error Guide
+
+`Ask::Linear::Errors` provides structured knowledge for agents:
+
+```ruby
+# Look up GraphQL error extension codes
+Ask::Linear::Errors.for("AUTHENTICATION_ERROR")
+# => { message: "...", action: "..." }
+
+# Describe HTTP status codes
+Ask::Linear::Errors.status_code_description(401)
+# => "Unauthorized — API key is missing, invalid, or revoked."
+
+# Rate limit info
+Ask::Linear::Errors::RATE_LIMIT[:authenticated]
+# => "100 requests per minute per API key"
+
+# Pagination guidance
+Ask::Linear::Errors::PAGINATION[:cursor_based]
+# => "Linear uses cursor-based pagination with first/after or last/before arguments."
+```
+
+### Supported Error Codes
+
+| Extension Code | When It Occurs |
+|---|---|
+| `AUTHENTICATION_ERROR` | Missing, invalid, or revoked API key |
+| `FORBIDDEN` | API key lacks permission for the resource |
+| `NOT_FOUND` | Resource doesn't exist or is inaccessible |
+| `RATE_LIMITED` | API rate limit exceeded (100 req/min/key) |
+| `INPUT_VALIDATION_ERROR` | Input data fails validation |
+| `DUPLICATE_INPUT` | Resource with same data already exists |
+| `INTERNAL_ERROR` | Linear server error |
+| `USER_SUSPENDED` | Authenticated user account is suspended |
+| `WORKSPACE_SUSPENDED` | Workspace is suspended or deactivated |
+
+## Client API
+
+### `Ask::Linear.client`
+
+Returns an authenticated `Ask::Linear::Client` wrapped in a `ClientProxy` that catches 401 errors.
+
+### `client.query(gql, variables = {})`
+
+Executes a GraphQL query or mutation against the Linear API.
+
+**Arguments:**
+- `gql` (String) — The GraphQL query or mutation string
+- `variables` (Hash) — Variables to interpolate into the query (optional)
+
+**Returns:** Hash with `"data"` key containing the response
+
+**Raises:**
+- `Ask::Auth::MissingCredential` if no API key is configured
+- `Ask::Auth::InvalidCredential` if the API key returns 401
+- `RuntimeError` if the API returns GraphQL errors
+
+### Example: Common Operations
+
+```ruby
+client = Ask::Linear.client
+
+# List teams
+teams = client.query("query { teams { nodes { id key name } } }")
+
+# List my assigned issues
+my_issues = client.query("query { viewer { assignedIssues { nodes { id identifier title state { name } } } } }")
+
+# Get workflow states for a team
+states = client.query("query($teamId: String!) { team(id: $teamId) { states { nodes { id name type } } } }",
+  teamId: "TEAM_ID")
+
+# Update issue state
+result = client.query(
+  "mutation($id: String!, $input: IssueUpdateInput!) { issueUpdate(id: $id, input: $input) { success issue { id identifier state { name } } } }",
+  { id: "ISSUE_ID", input: { stateId: "STATE_ID" } }
+)
+
+# Add comment
+result = client.query(
+  "mutation($input: CommentCreateInput!) { commentCreate(input: $input) { success comment { id body } } }",
+  { input: { issueId: "ISSUE_ID", body: "Working on this" } }
+)
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## License
+
+MIT

data/lib/ask/linear/client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "ask/auth"
+
+module Ask
+  module Linear
+    # Returns an authenticated GraphQL client for the Linear API.
+    #
+    # Resolves the API key via +Ask::Auth.resolve(:linear_api_key)+ and
+    # returns a +Client+ that wraps Faraday and sends GraphQL queries to
+    # +https://api.linear.app/graphql+.
+    #
+    # Configuration:
+    # - +read_timeout+: +30+ seconds
+    # - +open_timeout+: +10+ seconds
+    #
+    # @example
+    #   client = Ask::Linear.client
+    #   result = client.query("query { teams { nodes { id name } } }")
+    #
+    # @return [Ask::Linear::Client] an authenticated GraphQL client
+    # @raise [Ask::Auth::MissingCredential] if no Linear API key is configured
+    # @raise [Ask::Auth::InvalidCredential] if the API key is rejected (401)
+    # @raise [ArgumentError] if query arguments are invalid
+    # @raise [RuntimeError] if Linear returns GraphQL error messages
+    # @raise [Faraday::Error] if the HTTP request fails
+    def self.client
+      api_key = Ask::Auth.resolve(:linear_api_key)
+      ClientProxy.new(Client.new(api_key))
+    end
+
+    # A lightweight GraphQL client for the Linear API.
+    class Client
+      # Base URL for the Linear GraphQL API.
+      BASE_URL = "https://api.linear.app/graphql"
+
+      # @return [Faraday::Connection] the underlying Faraday connection
+      attr_reader :connection
+
+      # @param api_key [String] Linear personal API key
+      def initialize(api_key)
+        @api_key = api_key
+        @connection = Faraday.new(url: BASE_URL) do |f|
+          f.request :json
+          f.response :json
+          f.response :raise_error
+          f.options.read_timeout = 30
+          f.options.open_timeout = 10
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Execute a GraphQL query or mutation against the Linear API.
+      #
+      # @param gql [String] GraphQL query or mutation string
+      # @param variables [Hash] Variables to interpolate into the query (default: {})
+      # @return [Hash] Parsed response body from the Linear API
+      # @raise [ArgumentError] if +gql+ is not a String or +variables+ is not a Hash
+      # @raise [RuntimeError] if the API returns errors in the response body
+      # @raise [Faraday::Error] if the HTTP request fails
+      def query(gql, variables = {})
+        unless gql.is_a?(::String)
+          raise ::ArgumentError, "gql must be a String, got #{gql.class}"
+        end
+
+        unless variables.is_a?(::Hash)
+          raise ::ArgumentError, "variables must be a Hash, got #{variables.class}"
+        end
+
+        response = @connection.post do |req|
+          req.headers["Authorization"] = @api_key
+          req.body = { query: gql, variables: variables }
+        end
+
+        body = response.body
+
+        if body.is_a?(Hash) && body["errors"]
+          messages = body["errors"].map { |e| e["message"] }.join("; ")
+          raise ::RuntimeError, "Linear API error: #{messages}"
+        end
+
+        body
+      end
+    end
+
+    # Proxies method calls to a +Client+, converting authentication
+    # errors into +Ask::Auth::InvalidCredential+.
+    class ClientProxy < BasicObject
+      def initialize(client)
+        @client = client
+      end
+
+      def method_missing(name, ...)
+        @client.public_send(name, ...)
+      rescue ::Faraday::UnauthorizedError => e
+        response = e.response
+        status = response.is_a?(::Hash) ? response[:status] : nil
+        if status == 401
+          ::Kernel.raise ::Ask::Auth::InvalidCredential, :linear_api_key
+        end
+        ::Kernel.raise
+      rescue ::Faraday::ClientError => e
+        response = e.response
+        status = response.is_a?(::Hash) ? response[:status] : nil
+        if status == 401
+          ::Kernel.raise ::Ask::Auth::InvalidCredential, :linear_api_key
+        end
+        ::Kernel.raise
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @client.respond_to?(name, include_private) || super
+      end
+    end
+  end
+end

data/lib/ask/linear/context.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module Linear
+    # Human-readable description of the Linear service context.
+    DESCRIPTION = "Linear — issue tracking, project management, roadmaps, sprints"
+
+    # Base URL for Linear API documentation.
+    DOCS_URL = "https://developers.linear.app/docs"
+
+    # URL for the Linear GraphQL API schema (available via introspection).
+    GRAPHQL_URL = "https://api.linear.app/graphql"
+
+    # Credential name used with Ask::Auth.resolve.
+    AUTH_NAME = :linear_api_key
+
+    # Instructions for obtaining a Linear personal API key.
+    AUTH_HOW = "https://linear.app/settings/api — generate a personal API key"
+
+    # Gem name for the Linear API client.
+    GEM_NAME = "faraday"
+
+    # Required gem version constraint.
+    GEM_VERSION = "~> 2.0"
+
+    # URL for Faraday Ruby library documentation.
+    GEM_DOCS = "https://lostisland.github.io/faraday"
+
+    # Quick-start Ruby code snippet for agents to copy-paste.
+    QUICK_START = <<~RUBY
+      client = Ask::Linear.client
+      # List teams
+      result = client.query("query { teams { nodes { id key name } } }")
+      # Get issue by ID
+      result = client.query("query($id: String!) { issue(id: $id) { id identifier title description url } }", { id: "ISSUE_ID" })
+      # Create issue
+      result = client.query("mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }", { input: { teamId: "TEAM_ID", title: "New issue", description: "Description" } })
+      # List issues for a team
+      result = client.query("query { team(id: \\"TEAM_ID\\") { issues { nodes { id identifier title state { name } priority } } } }")
+    RUBY
+  end
+end

data/lib/ask/linear/error_guide.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Ask
+  module Linear
+    # Structured error knowledge for AI agents working with the Linear API.
+    #
+    # Provides human-readable guidance for common HTTP status codes, rate
+    # limiting, authentication errors, and GraphQL error extensions
+    # encountered when using the Linear GraphQL API.
+    module Errors
+      # Rate limit information.
+      #
+      # - Authenticated requests: 100 requests per minute per API key
+      #
+      # When rate-limited, Linear returns a 429 status code. The agent
+      # should wait and retry.
+      RATE_LIMIT = {
+        authenticated: "100 requests per minute per API key",
+        error_class: "Faraday::ClientError (HTTP 429)",
+        action: "Wait for the rate limit window and retry. Linear uses a sliding window rate limiter."
+      }.freeze
+
+      # Common HTTP status codes returned by the Linear GraphQL API and how to handle them.
+      #
+      # Linear wraps most errors in GraphQL error responses (HTTP 200 with errors body),
+      # but some authentication and rate-limit errors come through as HTTP status codes.
+      STATUS_CODES = {
+        200 => "OK — The request succeeded. Check the response body for GraphQL errors.",
+        400 => "Bad Request — The GraphQL query is malformed or invalid variables.",
+        401 => "Unauthorized — API key is missing, invalid, or revoked. Re-authenticate.",
+        403 => "Forbidden — API key lacks access to the requested resource.",
+        404 => "Not Found — The requested resource does not exist.",
+        422 => "Unprocessable Entity — Validation failed. Check request parameters.",
+        429 => "Too Many Requests — Rate limit exceeded. Wait before retrying.",
+        500 => "Internal Server Error — Linear server issue. Retry with backoff.",
+        503 => "Service Unavailable — Linear is temporarily unavailable. Retry later."
+      }.freeze
+
+      # Pagination guidance for the Linear GraphQL API.
+      PAGINATION = {
+        cursor_based: "Linear uses cursor-based pagination with first/after or last/before arguments.",
+        page_size: "Use the 'first' argument to control page size (default: 50, max: 100).",
+        nodes: "List fields return a connection with 'nodes', 'pageInfo', and 'edges'.",
+        page_info: "Check pageInfo.hasNextPage and pageInfo.hasPreviousPage for more pages.",
+        example: 'query { issues(first: 50, after: "cursor") { nodes { id title } pageInfo { hasNextPage endCursor } } }'
+      }.freeze
+
+      # Map of common GraphQL error messages to human-readable guidance.
+      #
+      # Linear returns errors in the GraphQL format: +{ "errors": [{ "message": "...", "extensions": { ... } }] }+
+      ERRORS = {
+        "AUTHENTICATION_ERROR" => {
+          message: "The API key is missing, invalid, or has been revoked.",
+          action: "Generate a new API key at https://linear.app/settings/api and update your credentials."
+        },
+        "FORBIDDEN" => {
+          message: "Your API key does not have permission to access this resource.",
+          action: "Check that your API key has the necessary scopes. You may need an admin to grant access."
+        },
+        "NOT_FOUND" => {
+          message: "The requested resource could not be found.",
+          action: "Verify the ID or identifier is correct. Resources may have been deleted or you may not have access."
+        },
+        "RATE_LIMITED" => {
+          message: "API rate limit exceeded.",
+          action: "Wait before retrying. Linear allows 100 requests per minute per API key."
+        },
+        "INPUT_VALIDATION_ERROR" => {
+          message: "The input data failed validation.",
+          action: "Check required fields, data types, and constraints. Linear returns detailed error messages."
+        },
+        "DUPLICATE_INPUT" => {
+          message: "A resource with the same input data already exists.",
+          action: "Check for existing resources before creating new ones with duplicate fields."
+        },
+        "INTERNAL_ERROR" => {
+          message: "Linear encountered an internal server error.",
+          action: "Retry with exponential backoff. If the issue persists, check https://linearstatus.com."
+        },
+        "USER_SUSPENDED" => {
+          message: "The authenticated user account has been suspended.",
+          action: "Contact your Linear workspace administrator to resolve the suspension."
+        },
+        "WORKSPACE_SUSPENDED" => {
+          message: "The Linear workspace has been suspended or deactivated.",
+          action: "Contact your Linear workspace administrator or check billing status."
+        }
+      }.freeze
+
+      # Look up guidance for a GraphQL error extension code.
+      #
+      # @param error_code [String] The error extension code (e.g., "AUTHENTICATION_ERROR")
+      # @return [Hash, nil] A hash with +:message+ and +:action+ keys, or nil if unknown
+      def self.for(error_code)
+        ERRORS[error_code]
+      end
+
+      # Describe an HTTP status code.
+      #
+      # @param code [Integer] HTTP status code
+      # @return [String, nil] Description of the status code
+      def self.status_code_description(code)
+        STATUS_CODES[code]
+      end
+    end
+  end
+end

data/lib/ask/linear/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module Linear
+    VERSION = '0.1.0'
+  end
+end

data/lib/ask-linear.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ask/linear/version"
+require_relative "ask/linear/context"
+require_relative "ask/linear/client"
+require_relative "ask/linear/error_guide"

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: ask-linear
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides authenticated GraphQL client, context metadata, and error guide
+  for AI agents working with the Linear API.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask-linear.rb
+- lib/ask/linear/client.rb
+- lib/ask/linear/context.rb
+- lib/ask/linear/error_guide.rb
+- lib/ask/linear/version.rb
+homepage: https://github.com/ask-rb/ask-linear
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Linear service context for the ask-rb ecosystem
+test_files: []