lexdrill 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a20cfbe4b7db3dbc41bec9f5e6bac7954660f81c5396bd39337b620f78038cfd
-  data.tar.gz: 6a26fc1605e888f21569d4109f774d85d753e6e17f6e0a40b220d071cda5549c
+  metadata.gz: 12866aced5d028c5f5951d0a201a7351090cc27adb617c73e317b80df3dcaa0f
+  data.tar.gz: 2e14d88608088fdbb6bd1a0071171696182deb828b840826bd3e7a7964f1f887
 SHA512:
-  metadata.gz: 664c053ae57b8f89b78364699dc865067e461086145c8be708e84473df83642966751bdec82c42e977f185dba6ca3799ae8aa65faa2ddd4e34f27245054a79ed
-  data.tar.gz: 6d3c8d58b6b1b198857287546c215e519b023d051020bd4980ffe1958a7103bdc1d2167811f28aa1db42d8b93233b85923137b5f39e107c4224042c60fdce7c4
+  metadata.gz: 8c8947fc580a75406e2a02b164092d49dc0bf66663ed55f0b5d395374e9f169b6bb330e84cdebedbb0ea91f5af88334c8bfa5f0532699b122b9d29d01eae7d50
+  data.tar.gz: 1b7c635562627735a1f85bc1656398f8782bcfaead000c24be594ade643748e89b2e0993215c853139fce1c3587758640c5b73e43e11b6de9293aedcb85fcf59

data/README.md

@@ -180,6 +180,57 @@ longer comes up automatically). If every word in the list has been
 mastered, `next` reports that on stderr and exits 1 instead of showing
 anything.
 
+### Google Sheets export
+
+`drill export` mirrors your word list (text only, no stats) into a tab of a
+Google Sheet you own, using **your own Google account** — not a service
+account key. That distinction matters: a service-account private key would
+have to be embedded in this published gem, meaning anyone who `gem install`s
+lexdrill would get it too. Instead, `drill` uses the OAuth 2.0 **Device
+Authorization Grant** ("visit this URL, enter this code," the same style of
+flow `gcloud auth login` uses) — you approve access to your own account
+once, and the resulting token is cached locally at
+`~/.drill.gcp-token.json` (mode `0600`), never published or shared.
+
+The OAuth client id/secret embedded in `lib/lexdrill/google_auth.rb` are
+**not** secret for this use — Google's own docs say client credentials for
+"TVs and Limited Input devices" / installed-app clients aren't treated as
+confidential. The actual secret is your personal refresh token, which is
+generated only after you interactively approve, and stays on your machine.
+
+#### One-time Google Cloud setup (you do this yourself)
+
+1. Go to <https://console.cloud.google.com>, create or select a project.
+2. **APIs & Services → Library** → search "Google Sheets API" → Enable.
+3. **APIs & Services → OAuth consent screen**: User type **External**;
+   publishing status **Testing** is fine — add your own Google account
+   under "Test users".
+4. **APIs & Services → Credentials → Create Credentials → OAuth client
+   ID** → Application type **"TVs and Limited Input devices"** (no redirect
+   URI needed). Copy the generated Client ID and Client secret into
+   `CLIENT_ID`/`CLIENT_SECRET` in `lib/lexdrill/google_auth.rb`.
+5. "Testing" publishing status has historically imposed a 7-day
+   refresh-token expiry for some scopes. If `drill export` starts asking
+   you to re-authorize every week, switch the consent screen to **"In
+   production"** — for the `spreadsheets` scope (not a "restricted" scope)
+   this just adds an "unverified app" click-through on first consent, no
+   Google review required.
+
+#### Using it
+
+```bash
+drill remote 'https://docs.google.com/spreadsheets/d/1opBP4APL5SUvepm9qwjIYRNtDZdoY1Ee87F5PWdxaMg/edit?usp=sharing'
+drill export Sheet1
+```
+
+The first `export` prints a URL and a short code — visit it, sign in with
+the Google account that has edit access to that spreadsheet, and approve.
+Every export after that is silent (the cached token refreshes itself
+automatically). If `<sheet-name>` doesn't exist yet as a tab in the
+spreadsheet, `export` creates it; either way it always **overwrites** the
+tab's contents with the current word list text (one word/phrase per row, no
+stats), so it stays an exact mirror even if the list shrinks.
+
 ### Commands
 
 | Command | What it does |
@@ -197,3 +248,5 @@ anything.
 | `drill stats` | Print all items as `<count>\t<phrase>` (tab-separated), sorted by show count, highest first |
 | `drill rand <n>` | `drill next` shows a word ~1-in-`n` times (`n=1` is every time, the default) |
 | `drill go <number>` | Jump so the next `drill next` shows item `<number>` (1-based, see `drill list`) — prints nothing itself; refuses a graduated item; has no effect while `drill beat rand` is active, since that mode ignores the counter entirely |
+| `drill remote <url>` | Set the Google Sheet to export to (global, parses the spreadsheet id out of a normal share URL) |
+| `drill export <sheet-name>` | Export the word list text to the named tab (created if it doesn't exist), overwriting it; first run triggers a one-time Google device-flow sign-in |

data/lib/lexdrill/cli.rb

@@ -17,7 +17,9 @@ class Lexdrill::CLI
     run_open: %w[open],
     run_stats: %w[stats],
     run_rand: %w[rand],
-    run_go: %w[go]
+    run_go: %w[go],
+    run_remote: %w[remote],
+    run_export: %w[export]
   }.freeze
 
   def self.start(argv = ARGV)
@@ -69,6 +71,9 @@ class Lexdrill::CLI
         drill stats        Print items as <count>\t<phrase>, tab-separated, highest count first
         drill rand <n>     drill next shows a word ~1-in-n times (n=1 is every time)
         drill go <number>  Jump so the next `next` shows item <number> (1-based, see drill list)
+        drill remote <url>          Set the Google Sheet to export to (global, ~/.drill.remote)
+        drill export <sheet-name>   Export the word list text to the given tab (overwrites its
+                                    contents); first run opens a one-time Google device-flow sign-in
     HELP
     0
   end
@@ -285,6 +290,77 @@ class Lexdrill::CLI
     1
   end
 
+  def run_remote
+    url = argv[1]
+    return print_remote_usage unless url
+
+    Lexdrill::Remote.set(url)
+    puts "remote spreadsheet set: #{Lexdrill::Remote.spreadsheet_id}"
+    0
+  rescue ArgumentError
+    print_invalid_remote_url(url)
+  end
+
+  def print_remote_usage
+    warn "usage: drill remote <google-sheets-url>"
+    1
+  end
+
+  def print_invalid_remote_url(url)
+    warn "drill: could not find a spreadsheet id in #{url.inspect}"
+    1
+  end
+
+  def run_export
+    sheet_name = argv[1]
+    return print_export_usage unless sheet_name
+    return print_no_remote unless Lexdrill::Remote.configured?
+
+    perform_export(sheet_name)
+  rescue Lexdrill::GoogleAuth::AuthError => error
+    warn "drill: #{error.message}"
+    1
+  rescue Lexdrill::SheetsClient::ApiError => error
+    print_sheets_api_error(error, sheet_name)
+  rescue Lexdrill::HTTPClient::NetworkError => error
+    warn "drill: network error talking to Google (#{error.message})"
+    1
+  end
+
+  def perform_export(sheet_name)
+    token = Lexdrill::GoogleAuth.ensure_token!
+    rows = export_rows
+    Lexdrill::SheetsClient.overwrite_sheet(Lexdrill::Remote.spreadsheet_id, sheet_name, rows, token)
+    puts "exported #{rows.size} word(s) to #{sheet_name.inspect}"
+    0
+  end
+
+  def export_rows
+    Lexdrill::WordList.words.map { |word| [word] }
+  end
+
+  def print_export_usage
+    warn "usage: drill export <sheet-name>"
+    1
+  end
+
+  def print_no_remote
+    warn "drill: no remote spreadsheet configured; run `drill remote <url>` first"
+    1
+  end
+
+  def print_sheets_api_error(error, sheet_name)
+    status = error.status
+    message = error.message
+    case status
+    when 404 then warn "drill: spreadsheet not found or not accessible with this Google account (check `drill remote`)"
+    when 403 then warn "drill: access denied — the signed-in Google account needs edit access to the spreadsheet"
+    when 400 then warn "drill: #{message} (is #{sheet_name.inspect} a real tab in the spreadsheet?)"
+    else warn "drill: Google Sheets API error (#{status}): #{message}"
+    end
+    1
+  end
+
   def print_unknown_command(command)
     warn "drill: unknown command #{command.inspect}"
     print_help

data/lib/lexdrill/google_auth.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+# Handles the Google OAuth 2.0 Device Authorization Grant ("visit this URL,
+# enter this code") so `drill export` can write to a Sheet as the user's own
+# Google account, without ever needing a service account key.
+#
+# CLIENT_ID/CLIENT_SECRET below are NOT confidential for this OAuth client
+# type ("TVs and Limited Input devices" / installed-app device flow) — see
+# README's "Google Sheets export" section for why it's safe to ship these in
+# published gem source. The actual secret is the refresh_token persisted at
+# PATH below, obtained only after this specific user's own interactive
+# consent, which never leaves this machine and is never published.
+module Lexdrill::GoogleAuth
+  PATH = File.join(Dir.home, ".drill.gcp-token.json")
+
+  CLIENT_ID = "608056429593-ncdgh4bnfpuf9486l2rlt7g763h1gl6g.apps.googleusercontent.com"
+  CLIENT_SECRET = "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"
+
+  SCOPE = "https://www.googleapis.com/auth/spreadsheets"
+  DEVICE_CODE_URL = "https://oauth2.googleapis.com/device/code"
+  TOKEN_URL = "https://oauth2.googleapis.com/token"
+  GRANT_TYPE_DEVICE = "urn:ietf:params:oauth:grant-type:device_code"
+  DEFAULT_POLL_INTERVAL = 5
+  DEFAULT_EXPIRES_IN = 1800
+  EXPIRY_SKEW = 60 # seconds of safety margin before treating a token as expired
+
+  class AuthError < StandardError; end
+
+  def self.ensure_token!
+    return login! unless configured?
+
+    data = load_token
+    return data["access_token"] if Time.now.to_i < data["expires_at"].to_i
+
+    refresh!
+  end
+
+  def self.configured?
+    File.exist?(PATH)
+  end
+
+  def self.clear!
+    FileUtils.rm_f(PATH)
+  end
+
+  def self.login!
+    device = request_device_code
+    print_instructions(device)
+    poll_for_token(device)
+  end
+
+  def self.request_device_code
+    response = Lexdrill::HTTPClient.post_form(DEVICE_CODE_URL, { "client_id" => CLIENT_ID, "scope" => SCOPE })
+    JSON.parse(response.body)
+  end
+  private_class_method :request_device_code
+
+  def self.print_instructions(device)
+    puts "To let lexdrill export to Google Sheets, visit:"
+    puts "  #{device['verification_url']}"
+    puts "and enter this code: #{device['user_code']}"
+    puts "Waiting for you to approve..."
+  end
+  private_class_method :print_instructions
+
+  def self.poll_for_token(device)
+    interval = (device["interval"] || DEFAULT_POLL_INTERVAL).to_i
+    deadline = Time.now.to_i + (device["expires_in"] || DEFAULT_EXPIRES_IN).to_i
+    loop do
+      check_not_expired(deadline)
+      sleep(interval)
+      outcome = classify_poll_result(attempt_token_exchange(device["device_code"]))
+      return outcome[:token] if outcome[:done]
+
+      interval += 5 if outcome[:slow_down]
+    end
+  end
+  private_class_method :poll_for_token
+
+  def self.check_not_expired(deadline)
+    return if Time.now.to_i <= deadline
+
+    raise AuthError, "device code expired before authorization completed; run the command again"
+  end
+  private_class_method :check_not_expired
+
+  def self.classify_poll_result(result)
+    return { done: true, token: persist_token(result) } if result["access_token"]
+
+    error = result["error"]
+    return { done: false } if error == "authorization_pending"
+    return { done: false, slow_down: true } if error == "slow_down"
+
+    raise AuthError, "Google authorization failed: #{error}"
+  end
+  private_class_method :classify_poll_result
+
+  def self.attempt_token_exchange(device_code)
+    response = Lexdrill::HTTPClient.post_form(TOKEN_URL, {
+                                                "client_id" => CLIENT_ID, "client_secret" => CLIENT_SECRET,
+                                                "device_code" => device_code, "grant_type" => GRANT_TYPE_DEVICE
+                                              })
+    JSON.parse(response.body)
+  end
+  private_class_method :attempt_token_exchange
+
+  def self.refresh!
+    data = load_token
+    params = {
+      "client_id" => CLIENT_ID, "client_secret" => CLIENT_SECRET,
+      "refresh_token" => data["refresh_token"], "grant_type" => "refresh_token"
+    }
+    handle_refresh_response(Lexdrill::HTTPClient.post_form(TOKEN_URL, params), data)
+  end
+
+  def self.handle_refresh_response(response, data)
+    body = JSON.parse(response.body)
+    raise_invalid_grant(body) if response.code == 400 && body["error"] == "invalid_grant"
+
+    data["access_token"] = body["access_token"]
+    data["expires_at"] = Time.now.to_i + body["expires_in"].to_i - EXPIRY_SKEW
+    save(data)
+    data["access_token"]
+  end
+  private_class_method :handle_refresh_response
+
+  def self.raise_invalid_grant(body)
+    clear!
+    raise AuthError, "Google access was revoked or expired (#{body['error_description']}); " \
+                     "run `drill export` again to re-authorize"
+  end
+  private_class_method :raise_invalid_grant
+
+  def self.persist_token(data)
+    token = {
+      "access_token" => data["access_token"],
+      "refresh_token" => data["refresh_token"],
+      "expires_at" => Time.now.to_i + data["expires_in"].to_i - EXPIRY_SKEW
+    }
+    save(token)
+    token["access_token"]
+  end
+  private_class_method :persist_token
+
+  def self.load_token
+    JSON.parse(File.read(PATH))
+  end
+  private_class_method :load_token
+
+  def self.save(token)
+    File.write(PATH, JSON.generate(token))
+    File.chmod(0o600, PATH) # the ONE lexdrill config file holding a real secret
+  end
+  private_class_method :save
+end

data/lib/lexdrill/http_client.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+# The only place lexdrill talks to Net::HTTP directly. Lexdrill::GoogleAuth
+# (form-encoded OAuth endpoints) and Lexdrill::SheetsClient (JSON REST) both
+# go through here, so every low-level connectivity failure (DNS, timeout,
+# TLS, connection refused) is normalized to a single NetworkError for
+# callers to handle, instead of each caller needing to know every possible
+# Net::HTTP/OpenSSL/socket exception class.
+module Lexdrill::HTTPClient
+  OPEN_TIMEOUT = 10
+  READ_TIMEOUT = 15
+
+  Response = Struct.new(:code, :body)
+
+  class NetworkError < StandardError; end
+
+  def self.post_form(url, params)
+    uri = URI(url)
+    perform(uri) { |http| http.post(uri.path, URI.encode_www_form(params)) }
+  end
+
+  def self.json_post(url, body:, headers: {})
+    json_request(Net::HTTP::Post, url, body, headers)
+  end
+
+  def self.json_put(url, body:, headers: {})
+    json_request(Net::HTTP::Put, url, body, headers)
+  end
+
+  def self.json_get(url, headers: {})
+    uri = URI(url)
+    request = build_get_request(uri, headers)
+    perform(uri) { |http| http.request(request) }
+  end
+
+  def self.build_get_request(uri, headers)
+    request = Net::HTTP::Get.new(uri.request_uri)
+    headers.each { |key, value| request[key] = value }
+    request
+  end
+  private_class_method :build_get_request
+
+  def self.json_request(method_class, url, body, headers)
+    uri = URI(url)
+    request = build_json_request(method_class, uri, body, headers)
+    perform(uri) { |http| http.request(request) }
+  end
+  private_class_method :json_request
+
+  def self.build_json_request(method_class, uri, body, headers)
+    request = method_class.new(uri.request_uri)
+    headers.each { |key, value| request[key] = value }
+    request["Content-Type"] = "application/json"
+    request.body = JSON.generate(body)
+    request
+  end
+  private_class_method :build_json_request
+
+  def self.perform(uri, &block)
+    response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                                   open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT, &block)
+    Response.new(response.code.to_i, response.body)
+  rescue StandardError => error
+    raise NetworkError, error.message
+  end
+  private_class_method :perform
+end

data/lib/lexdrill/remote.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Global "which Google Sheet to export to" setting. Lives at ~/.drill.remote
+# as a plain spreadsheet id, parsed out of a normal Google Sheets share URL.
+module Lexdrill::Remote
+  PATH = File.join(Dir.home, ".drill.remote")
+  URL_PATTERN = %r{/spreadsheets/d/([a-zA-Z0-9_-]+)}
+
+  def self.set(url)
+    id = extract_id(url)
+    raise ArgumentError, "no spreadsheet id found in #{url.inspect}" unless id
+
+    File.write(PATH, id)
+  end
+
+  def self.extract_id(url)
+    url[URL_PATTERN, 1]
+  end
+
+  def self.configured?
+    File.exist?(PATH)
+  end
+
+  def self.spreadsheet_id
+    File.read(PATH).strip if configured?
+  end
+end

data/lib/lexdrill/sheets_client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+
+# Thin wrapper around the Google Sheets API v4 REST endpoints needed by
+# `drill export`: create the target tab if it doesn't already exist, clear
+# its contents, write new rows into it, then auto-fit column A's width to
+# the content so long phrases aren't visually truncated.
+module Lexdrill::SheetsClient
+  BASE_URL = "https://sheets.googleapis.com/v4/spreadsheets"
+
+  class ApiError < StandardError
+    attr_reader :status
+
+    def initialize(status, message)
+      @status = status
+      super(message)
+    end
+  end
+
+  def self.overwrite_sheet(spreadsheet_id, sheet_name, rows, access_token)
+    sheet_id = ensure_sheet_exists(spreadsheet_id, sheet_name, access_token)
+    clear(spreadsheet_id, sheet_name, access_token)
+    update(spreadsheet_id, sheet_name, rows, access_token)
+    autofit_first_column(spreadsheet_id, sheet_id, access_token)
+  end
+
+  def self.ensure_sheet_exists(spreadsheet_id, sheet_name, access_token)
+    existing = find_sheet(spreadsheet_id, sheet_name, access_token)
+    return existing["sheetId"] if existing
+
+    add_sheet(spreadsheet_id, sheet_name, access_token)
+  end
+  private_class_method :ensure_sheet_exists
+
+  def self.find_sheet(spreadsheet_id, sheet_name, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}?fields=sheets.properties"
+    data = handle_response(Lexdrill::HTTPClient.json_get(url, headers: auth_header(access_token)))
+    data.fetch("sheets", []).map { |sheet| sheet["properties"] }.find { |props| props["title"] == sheet_name }
+  end
+  private_class_method :find_sheet
+
+  def self.add_sheet(spreadsheet_id, sheet_name, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}:batchUpdate"
+    body = { "requests" => [{ "addSheet" => { "properties" => { "title" => sheet_name } } }] }
+    result = handle_response(Lexdrill::HTTPClient.json_post(url, body: body, headers: auth_header(access_token)))
+    result.dig("replies", 0, "addSheet", "properties", "sheetId")
+  end
+  private_class_method :add_sheet
+
+  def self.autofit_first_column(spreadsheet_id, sheet_id, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}:batchUpdate"
+    dimensions = { "sheetId" => sheet_id, "dimension" => "COLUMNS", "startIndex" => 0, "endIndex" => 1 }
+    body = { "requests" => [{ "autoResizeDimensions" => { "dimensions" => dimensions } }] }
+    handle_response(Lexdrill::HTTPClient.json_post(url, body: body, headers: auth_header(access_token)))
+  end
+  private_class_method :autofit_first_column
+
+  def self.clear(spreadsheet_id, sheet_name, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}/values/#{encoded_range(sheet_name)}:clear"
+    handle_response(Lexdrill::HTTPClient.json_post(url, body: {}, headers: auth_header(access_token)))
+  end
+
+  def self.update(spreadsheet_id, sheet_name, rows, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}/values/#{encoded_range(sheet_name)}?valueInputOption=RAW"
+    body = { "range" => quoted_range(sheet_name), "majorDimension" => "ROWS", "values" => rows }
+    handle_response(Lexdrill::HTTPClient.json_put(url, body: body, headers: auth_header(access_token)))
+  end
+
+  def self.auth_header(token)
+    { "Authorization" => "Bearer #{token}" }
+  end
+  private_class_method :auth_header
+
+  # Quoting the sheet name defends against tab names containing spaces;
+  # harmless for plain names too. The URL path and the request body's
+  # "range" field must match exactly (Google rejects the request otherwise),
+  # so both go through this same quoting.
+  def self.quoted_range(sheet_name)
+    "'#{sheet_name}'"
+  end
+  private_class_method :quoted_range
+
+  def self.encoded_range(sheet_name)
+    URI.encode_www_form_component(quoted_range(sheet_name))
+  end
+  private_class_method :encoded_range
+
+  def self.handle_response(response)
+    status = response.code
+    return JSON.parse(response.body) if status == 200
+
+    raise ApiError.new(status, error_message(response))
+  end
+  private_class_method :handle_response
+
+  def self.error_message(response)
+    status = response.code
+    JSON.parse(response.body).dig("error", "message") || "HTTP #{status}"
+  rescue JSON::ParserError
+    "HTTP #{status}"
+  end
+  private_class_method :error_message
+end

data/lib/lexdrill/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lexdrill
-  VERSION = "0.13.0"
+  VERSION = "0.14.0"
 end

data/lib/lexdrill.rb

@@ -9,6 +9,10 @@ require_relative "lexdrill/stats"
 require_relative "lexdrill/word_list"
 require_relative "lexdrill/toggle"
 require_relative "lexdrill/rand"
+require_relative "lexdrill/remote"
+require_relative "lexdrill/http_client"
+require_relative "lexdrill/google_auth"
+require_relative "lexdrill/sheets_client"
 require_relative "lexdrill/shell_snippet"
 require_relative "lexdrill/inspector"
 require_relative "lexdrill/colorizer"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lexdrill
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Siarhei Kisliak
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-07-11 00:00:00.000000000 Z
 dependencies: []
 description: lexdrill prints a vocabulary word or phrase on demand, tracking how often
   each one has been shown.
@@ -32,9 +32,13 @@ files:
 - lib/lexdrill/counter.rb
 - lib/lexdrill/default_words.rb
 - lib/lexdrill/format.rb
+- lib/lexdrill/google_auth.rb
+- lib/lexdrill/http_client.rb
 - lib/lexdrill/inspector.rb
 - lib/lexdrill/line_formatter.rb
 - lib/lexdrill/rand.rb
+- lib/lexdrill/remote.rb
+- lib/lexdrill/sheets_client.rb
 - lib/lexdrill/shell_snippet.rb
 - lib/lexdrill/stats.rb
 - lib/lexdrill/toggle.rb