ask-linear 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cdf635069d34d0554d7e73ff22a0b589627ab59ace75b8376cfff7b11a502d5
-  data.tar.gz: 81cc288e84cb63fb8b622032adbdc911844cbe29097d2b99f5d0a19548fc8f69
+  metadata.gz: b2d2cc4fa5d5715fdfbf074dfd3e6c64a758e65f5387ab97cf5a07c4aac6ab35
+  data.tar.gz: 2be587d1288bba6f5acae2b011c71a74c70d4f9d7f7b0831fd2df98e611a46e5
 SHA512:
-  metadata.gz: 75e4a052079f42fdb445fcaea78010597c19708a5872a399c970b0f28f72c0ce77a76c0b6df4fe9d2c5681a060cff28cba750fd8de999e6438f745297c7ce87f
-  data.tar.gz: e4e4cb88175a66383b416409f85e05ad2661168f28df182dd82c230429d3ec1b2fef341886f12255a3434af258d74bfc1a40beeff104298f6e4d59b53bbcd631
+  metadata.gz: 15b294da6df23b368b697fc8594e5e6e5fb5a81c3175c8486b24e34b69a22675a336eafb2ac1178eff154415b985d71e7d173276b585a5ff3e3e2602ca660b43
+  data.tar.gz: 9f03b1c574e47f71fd445c80d2a36100ecaaa83ed426c5ef78cbac5237a4ff70ac2e43de1e5eca863a91ec06175e4b7cf6c41138b75ec97ad668c30a43384ac9

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+## [0.1.2] - 2026-06-25
+
+### Changed
+- Gemspec validation test. Infrastructure: rubocop, overcommit, bin/setup, CI matrix.
+# Changelog
+
+## [0.1.1] - 2026-06-21
+
+### Added
+
+- Initial release of `ask-linear` — Linear service context for the ask-rb ecosystem.
+- **context.rb** — Metadata constants for AI system prompts: `DESCRIPTION`, `DOCS_URL`, `GRAPHQL_URL`, `AUTH_NAME`, `AUTH_HOW`, `GEM_NAME`, `GEM_DOCS`, `QUICK_START`
+- **client.rb** — `Ask::Linear.client` returns an authenticated GraphQL client via `Ask::Auth.resolve(:linear_api_key)`. Uses Faraday to send GraphQL queries to the Linear API at `https://api.linear.app/graphql`. Wraps client in `ClientProxy` to convert `Faraday::UnauthorizedError` (HTTP 401) to `Ask::Auth::InvalidCredential`.
+- **error_guide.rb** — `Ask::Linear::Errors` with rate limit info, HTTP status code descriptions, and GraphQL error extension guidance for agents.
+- **Dependencies:** `ask-auth ~> 0.1`, `faraday ~> 2.0`
+- **Testing:** 26 tests, 62 assertions covering context constants, client auth flow, and error guide lookups.

data/lib/ask/linear/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "faraday"
+require "faraday/retry"
 require "ask/auth"
 
 module Ask
@@ -14,6 +15,7 @@ module Ask
     # Configuration:
     # - +read_timeout+: +30+ seconds
     # - +open_timeout+: +10+ seconds
+    # - +retry+: up to 3 retries on 429 (rate-limit) and 5xx (server) errors
     #
     # @example
     #   client = Ask::Linear.client
@@ -43,6 +45,11 @@ module Ask
         @api_key = api_key
         @connection = Faraday.new(url: BASE_URL) do |f|
           f.request :json
+          f.request :retry, max: 3,
+                            interval: 1.0,
+                            max_interval: 10.0,
+                            backoff_factor: 2.0,
+                            retry_statuses: [429, 500, 502, 503]
           f.response :json
           f.response :raise_error
           f.options.read_timeout = 30

data/lib/ask/linear/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Linear
-    VERSION = '0.1.0'
+    VERSION = '0.1.2'
   end
 end

data/lib/ask/skills/linear.use_linear/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: linear.use_linear
+description: How to navigate the Linear API with GraphQL — explore the schema, build queries, paginate, and handle errors
+---
+
+Use this skill when you need to interact with Linear — managing issues, teams,
+projects, sprints, or workflows. Unlike other service gems, Linear uses a raw
+GraphQL API — there's no convenience client for each endpoint.
+
+## Step 1: Get the Client
+
+```ruby
+client = Ask::Linear.client
+```
+
+This returns a `Faraday`-based client that sends HTTP POST to
+`https://api.linear.app/graphql`. It expects a valid Linear API key resolved
+via `Ask::Auth.resolve(:linear_api_key)`.
+
+If you get an auth error, read `Ask::Linear::Context::AUTH_HOW` for API key setup.
+
+## Step 2: Explore the Context
+
+The gem ships with structured context you should reference:
+
+```ruby
+Ask::Linear::Context::DOCS_URL       # Linear developer docs
+Ask::Linear::Context::GRAPHQL_URL    # GraphQL endpoint (for introspection)
+Ask::Linear::Context::QUICK_START    # Query/mutation examples
+```
+
+The `QUICK_START` constant has working examples for teams, issues, and mutations.
+
+## Step 3: Use GraphQL Introspection to Discover the Schema
+
+Since Linear is GraphQL, you can introspect the schema to discover types,
+queries, and mutations:
+
+```ruby
+# List all query fields
+result = client.query("
+  query {
+    __schema {
+      queryType {
+        fields {
+          name
+          description
+        }
+      }
+    }
+  }
+")
+```
+
+For a specific type:
+```ruby
+result = client.query("
+  query {
+    __type(name: \"Issue\") {
+      name
+      fields {
+        name
+        type {
+          name
+          kind
+        }
+      }
+    }
+  }
+")
+```
+
+For finding all mutations:
+```ruby
+result = client.query("
+  query {
+    __schema {
+      mutationType {
+        fields {
+          name
+          args { name type { name } }
+        }
+      }
+    }
+  }
+")
+```
+
+## Step 4: Common Query Patterns
+
+**List teams:**
+```ruby
+client.query("query { teams { nodes { id key name } } }")
+```
+
+**List issues for a team:**
+```ruby
+client.query("query { team(id: \"TEAM_ID\") { issues(first: 50) { nodes { id identifier title state { name } priority } } } }")
+```
+
+**Get issue details:**
+```ruby
+client.query("query($id: String!) { issue(id: $id) { id identifier title description url assignee { name } } }", { id: "ISSUE_ID" })
+```
+
+**Create an issue:**
+```ruby
+client.query("mutation($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier title url } } }", { input: { teamId: "TEAM_ID", title: "New issue", description: "Description" } })
+```
+
+**Search issues:**
+```ruby
+client.query("query { issues(filter: { title: { contains: \"search term\" } }) { nodes { id identifier title } } }")
+```
+
+## Step 5: Variable Syntax
+
+Linear's GraphQL API requires exact type names. Use introspection (`__type`)
+to find available input types. Variables are passed as a hash:
+
+```ruby
+client.query("query($id: String!) { issue(id: $id) { id title } }", { id: "abc123" })
+```
+
+The second argument is variables — it's passed as the second parameter to
+Faraday's `post`.
+
+## Step 6: Authentication & Common Errors
+
+For error guidance, use:
+
+```ruby
+Ask::Linear::Errors.for("AUTHENTICATION_ERROR")
+Ask::Linear::Errors.status_code_description(429)
+Ask::Linear::Errors::PAGINATION
+```
+
+Common scenarios:
+- **401**: API key invalid or revoked → generate new key at Linear settings
+- **429**: Rate limited (100 req/min per key) → wait and retry
+- **GraphQL errors**: Query returns 200 with `errors` array → check field names
+- **INPUT_VALIDATION_ERROR**: Wrong argument types → check schema for exact types
+
+## Step 7: Pagination
+
+Linear uses cursor-based connection pagination:
+
+```ruby
+# Get first page
+page = client.query("query { issues(first: 50) { nodes { id title } pageInfo { hasNextPage endCursor } } }")
+# Next page:
+page = client.query("query($cursor: String) { issues(first: 50, after: $cursor) { nodes { id title } pageInfo { hasNextPage endCursor } } }", { cursor: page.data.issues.pageInfo.endCursor }) while page.data.issues.pageInfo.hasNextPage
+```
+
+Use `first`/`after` for forward pagination, `last`/`before` for backward.
+
+## Step 8: Fallback Strategy
+
+1. Check `Ask::Linear::Context::DOCS_URL` for documentation
+2. Use GraphQL introspection to discover the schema
+3. Linear's API returns helpful error messages — read the `errors` array
+4. For complex queries, build them incrementally — start simple, add fields

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-linear
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Kaka Ruto
@@ -13,14 +13,14 @@ dependencies:
   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
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  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
@@ -87,6 +101,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/ask-linear.rb
@@ -94,10 +109,14 @@ files:
 - lib/ask/linear/context.rb
 - lib/ask/linear/error_guide.rb
 - lib/ask/linear/version.rb
+- lib/ask/skills/linear.use_linear/SKILL.md
 homepage: https://github.com/ask-rb/ask-linear
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-linear
+  source_code_uri: https://github.com/ask-rb/ask-linear
+  changelog_uri: https://github.com/ask-rb/ask-linear/blob/master/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib