lexdrill 0.13.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a20cfbe4b7db3dbc41bec9f5e6bac7954660f81c5396bd39337b620f78038cfd
-  data.tar.gz: 6a26fc1605e888f21569d4109f774d85d753e6e17f6e0a40b220d071cda5549c
+  metadata.gz: 36e9bb140cbbb757b2c9703b8cd122a9fd62a3faa108c4cc0072755391acb65f
+  data.tar.gz: b3502832141a5b7e751f69c5b6d8e729c640f5896300053b96f99fe068968b73
 SHA512:
-  metadata.gz: 664c053ae57b8f89b78364699dc865067e461086145c8be708e84473df83642966751bdec82c42e977f185dba6ca3799ae8aa65faa2ddd4e34f27245054a79ed
-  data.tar.gz: 6d3c8d58b6b1b198857287546c215e519b023d051020bd4980ffe1958a7103bdc1d2167811f28aa1db42d8b93233b85923137b5f39e107c4224042c60fdce7c4
+  metadata.gz: f89f5aa67e5ad3170d1cd956a4c0d53ffca66993f5b94ad55a3f9ef6e32bbaa8befb8d522e03506c761826a4273b1f86f72c4e92c2230c6d2c4b2906149bb70b
+  data.tar.gz: ac7a2afdfbdff3fe694b4ec90f30eaa7c418707a9370697033cadabf0d2b389f68f5356404ab62afbff30f685d16316399777721861ffe31c2e95970047d974f

data/README.md

@@ -180,6 +180,106 @@ 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 <sheet-name>` mirrors your word list (text only, no stats)
+into a tab of a Google Sheet you own; `drill import <sheet-name>` reads it
+back. There are two ways to authenticate — pick whichever you prefer:
+
+- **`drill remote <url>`** — a **service account** you create yourself. No
+  interactive sign-in, ever; you share the spreadsheet with the service
+  account's email address once, and `drill` uses a local private key file
+  to sign its own requests.
+- **`drill oauth <url>`** — your **personal Google login**, via a one-time
+  interactive OAuth approval. No GCP service account needed, but you (or
+  anyone using the gem) has to click through a sign-in flow once.
+
+If both are configured, whichever you set **more recently** wins — running
+`drill oauth <url>` after `drill remote <url>` switches `export`/`import`
+over to the personal-login flow, and vice versa.
+
+Either way, `export` always **overwrites** the named tab (creating it
+first if it doesn't exist yet) with the current word list, one phrase per
+row, so it stays an exact mirror even if the list shrinks. `import` is the
+reverse: it reads column A of the tab (ignoring any other columns, like an
+old export's show counts) and **replaces** your local `.drill.txt` —
+useful for editing the list in Sheets and pulling changes back down, or
+seeding a fresh machine from an existing sheet.
+
+#### Option A: service account (`drill remote`)
+
+No embedded secret, no interactive consent screen — but it does require a
+one-time Google Cloud Console setup, and the resulting private key file is
+a real secret you must keep local.
+
+1. Go to <https://console.cloud.google.com>, select a project (reuse the
+   one from Option B if you've already set that up), and make sure
+   **Google Sheets API** is enabled (**APIs & Services → Library**).
+2. **IAM & Admin → Service Accounts → "+ CREATE SERVICE ACCOUNT"**. Name it
+   anything (e.g. `lexdrill-export`); skip granting it any project-level
+   roles — it doesn't need any, since access comes from sharing the
+   document directly.
+3. Click into the new service account → **Keys → Add Key → Create new key
+   → JSON → Create**. This downloads a `.json` file — **this is a real
+   secret**, equivalent to a password. Never commit it, publish it, or
+   share it with anyone.
+4. Note the service account's email (looks like
+   `name@your-project-id.iam.gserviceaccount.com` — also the `client_email`
+   field in the downloaded JSON).
+5. Open your target Google Sheet → **Share** → paste that email → grant
+   **Editor** access → uncheck "Notify people" → Share.
+6. Save the downloaded key file to `~/.drill.gcp-service-account.json` on
+   your machine (`drill` reads it from that fixed path and sets it to mode
+   `0600`; it's never embedded in the gem or committed anywhere).
+
+```bash
+drill remote 'https://docs.google.com/spreadsheets/d/1opBP4APL5SUvepm9qwjIYRNtDZdoY1Ee87F5PWdxaMg/edit?usp=sharing'
+drill export Sheet1
+```
+
+No sign-in prompt — every call authenticates silently by signing a fresh,
+short-lived JWT with the local key file.
+
+#### Option B: personal login (`drill oauth`)
+
+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 (this is fundamentally different from the service account's
+private key above, which genuinely is a secret). The actual secret is your
+personal refresh token, generated only after you interactively approve.
+
+1. Go to <https://console.cloud.google.com>, create or select a project,
+   enable **Google Sheets API**.
+2. **APIs & Services → OAuth consent screen**: User type **External**;
+   publishing status **Testing** is fine — add your own Google account
+   under "Test users".
+3. **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`.
+4. "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.
+
+```bash
+drill oauth 'https://docs.google.com/spreadsheets/d/1opBP4APL5SUvepm9qwjIYRNtDZdoY1Ee87F5PWdxaMg/edit?usp=sharing'
+drill export Sheet1
+```
+
+The first `export`/`import` 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 call after that is silent (the cached token refreshes
+itself automatically).
+
 ### Commands
 
 | Command | What it does |
@@ -197,3 +297,7 @@ 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 used by the service account flow (global, parses the spreadsheet id out of a normal share URL); whichever of `drill remote`/`drill oauth` was set more recently wins |
+| `drill oauth <url>` | Set the Google Sheet used by the OAuth (personal-login) flow (global, parses the spreadsheet id out of a normal share URL); whichever of `drill remote`/`drill oauth` was set more recently wins |
+| `drill export <sheet-name>` | Export the word list text to the named tab (created if it doesn't exist), overwriting it; uses whichever of `drill remote`/`drill oauth` was configured most recently (first OAuth use triggers a one-time Google device-flow sign-in) |
+| `drill import <sheet-name>` | Replace the local word list with column A of the named tab |

data/lib/lexdrill/cli.rb

@@ -17,7 +17,11 @@ 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_oauth: %w[oauth],
+    run_export: %w[export],
+    run_import: %w[import]
   }.freeze
 
   def self.start(argv = ARGV)
@@ -69,6 +73,13 @@ 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 used by a local service account key
+                                    (~/.drill.gcp-service-account.json) — no interactive sign-in
+        drill oauth <url>           Set the Google Sheet used by the OAuth (personal-login) flow
+        drill export <sheet-name>   Export the word list text to the given tab (overwrites its
+                                    contents); uses whichever of drill remote/drill oauth was set
+                                    more recently (oauth opens a one-time sign-in on first use)
+        drill import <sheet-name>   Replace the local word list with column A of the given tab
     HELP
     0
   end
@@ -285,6 +296,159 @@ 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_oauth
+    url = argv[1]
+    return print_oauth_usage unless url
+
+    Lexdrill::OauthRemote.set(url)
+    puts "oauth spreadsheet set: #{Lexdrill::OauthRemote.spreadsheet_id}"
+    0
+  rescue ArgumentError
+    print_invalid_oauth_url(url)
+  end
+
+  def print_oauth_usage
+    warn "usage: drill oauth <google-sheets-url>"
+    1
+  end
+
+  def print_invalid_oauth_url(url)
+    warn "drill: could not find a spreadsheet id in #{url.inspect}"
+    1
+  end
+
+  # Uses whichever of `drill remote` (service account) / `drill oauth`
+  # (personal login) was set more recently, so switching between them with
+  # either command always takes effect. Returns [spreadsheet_id,
+  # access_token], or nil if neither is configured.
+  def sheets_target
+    case latest_remote_kind
+    when :remote then [Lexdrill::Remote.spreadsheet_id, Lexdrill::ServiceAccountAuth.fetch_token!]
+    when :oauth then [Lexdrill::OauthRemote.spreadsheet_id, Lexdrill::GoogleAuth.ensure_token!]
+    end
+  end
+
+  def latest_remote_kind
+    remote_set = Lexdrill::Remote.configured?
+    oauth_set = Lexdrill::OauthRemote.configured?
+    return :remote if remote_set && (!oauth_set || newer?(Lexdrill::Remote::PATH, Lexdrill::OauthRemote::PATH))
+    return :oauth if oauth_set
+
+    nil
+  end
+
+  def newer?(path, other_path) = File.mtime(path) >= File.mtime(other_path)
+
+  def run_export
+    sheet_name = argv[1]
+    return print_export_usage unless sheet_name
+
+    target = sheets_target
+    return print_no_remote unless target
+
+    perform_export(sheet_name, *target)
+  rescue Lexdrill::GoogleAuth::AuthError, Lexdrill::ServiceAccountAuth::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, spreadsheet_id, token)
+    rows = export_rows
+    Lexdrill::SheetsClient.overwrite_sheet(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>` (service account) " \
+         "or `drill oauth <url>` (personal login) first"
+    1
+  end
+
+  def run_import
+    sheet_name = argv[1]
+    return print_import_usage unless sheet_name
+
+    target = sheets_target
+    return print_no_remote unless target
+
+    perform_import(sheet_name, *target)
+  rescue Lexdrill::GoogleAuth::AuthError, Lexdrill::ServiceAccountAuth::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_import(sheet_name, spreadsheet_id, token)
+    words = Lexdrill::SheetsClient.read_column(spreadsheet_id, sheet_name, token)
+    return print_empty_import(sheet_name) if words.empty?
+
+    File.write(Lexdrill::WordList::PATH, "#{words.join("\n")}\n", encoding: "UTF-8")
+    puts "imported #{words.size} word(s) from #{sheet_name.inspect}"
+    0
+  end
+
+  def print_import_usage
+    warn "usage: drill import <sheet-name>"
+    1
+  end
+
+  def print_empty_import(sheet_name)
+    warn "drill: #{sheet_name.inspect} has no data to import"
+    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 (check `drill remote`/`drill oauth`)"
+    when 403 then warn "drill: access denied — make sure the spreadsheet is shared with the right account"
+    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/oauth_remote.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Global "which Google Sheet to export to via the OAuth device-flow login"
+# setting. Lives at ~/.drill.oauth-remote as a plain spreadsheet id, parsed
+# out of a normal Google Sheets share URL. Set via `drill oauth <url>`.
+# See Lexdrill::Remote for the separate, service-account-based flow.
+module Lexdrill::OauthRemote
+  PATH = File.join(Dir.home, ".drill.oauth-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/remote.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Global "which Google Sheet to export to via a service account" setting.
+# Lives at ~/.drill.remote as a plain spreadsheet id, parsed out of a normal
+# Google Sheets share URL. Set via `drill remote <url>` — the user shares
+# that spreadsheet with their service account's email directly in Google
+# Sheets, so no interactive Google sign-in is needed at export/import time.
+# See Lexdrill::OauthRemote for the separate, personal-login-based flow.
+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/service_account_auth.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "base64"
+
+# Authenticates to the Sheets API as a Google service account, using the
+# JWT Bearer Token flow (RFC 7523) — no interactive consent, no refresh
+# token to cache: a fresh short-lived JWT is signed and exchanged for an
+# access token on every call. The service account's private key lives in a
+# JSON file the user downloads themselves from Google Cloud Console and
+# saves locally at PATH below — it is never embedded in gem source, never
+# published, and lexdrill never writes or transmits it anywhere except in
+# the signed JWT sent directly to Google's own token endpoint.
+module Lexdrill::ServiceAccountAuth
+  PATH = File.join(Dir.home, ".drill.gcp-service-account.json")
+  TOKEN_URL = "https://oauth2.googleapis.com/token"
+  SCOPE = "https://www.googleapis.com/auth/spreadsheets"
+  GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+  TOKEN_LIFETIME = 3600
+
+  class AuthError < StandardError; end
+
+  def self.configured?
+    File.exist?(PATH)
+  end
+
+  def self.fetch_token!
+    key = load_key
+    jwt = build_jwt(key)
+    exchange_jwt(jwt)
+  end
+
+  def self.load_key
+    JSON.parse(File.read(PATH))
+  rescue Errno::ENOENT
+    raise AuthError, "no service account key found at #{PATH} — see README's service account setup"
+  rescue JSON::ParserError
+    raise AuthError, "#{PATH} is not valid JSON"
+  end
+  private_class_method :load_key
+
+  def self.build_jwt(key)
+    claims = jwt_claims(key.fetch("client_email"))
+    signing_input = "#{encode_segment(jwt_header)}.#{encode_segment(claims)}"
+    signature = sign(signing_input, key.fetch("private_key"))
+    "#{signing_input}.#{Base64.urlsafe_encode64(signature, padding: false)}"
+  end
+  private_class_method :build_jwt
+
+  def self.jwt_header
+    { "alg" => "RS256", "typ" => "JWT" }
+  end
+  private_class_method :jwt_header
+
+  def self.jwt_claims(client_email)
+    now = Time.now.to_i
+    { "iss" => client_email, "scope" => SCOPE, "aud" => TOKEN_URL, "iat" => now, "exp" => now + TOKEN_LIFETIME }
+  end
+  private_class_method :jwt_claims
+
+  def self.encode_segment(hash)
+    Base64.urlsafe_encode64(JSON.generate(hash), padding: false)
+  end
+  private_class_method :encode_segment
+
+  def self.sign(signing_input, private_key_pem)
+    OpenSSL::PKey::RSA.new(private_key_pem).sign(OpenSSL::Digest.new("SHA256"), signing_input)
+  end
+  private_class_method :sign
+
+  def self.exchange_jwt(jwt)
+    response = Lexdrill::HTTPClient.post_form(TOKEN_URL, { "grant_type" => GRANT_TYPE, "assertion" => jwt })
+    handle_token_response(response)
+  end
+  private_class_method :exchange_jwt
+
+  def self.handle_token_response(response)
+    body = JSON.parse(response.body)
+    return body.fetch("access_token") if response.code == 200
+
+    raise AuthError, "Google rejected the service account credentials: #{body['error_description'] || body['error']}"
+  end
+  private_class_method :handle_token_response
+end

data/lib/lexdrill/sheets_client.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+
+# Thin wrapper around the Google Sheets API v4 REST endpoints needed by
+# `drill export`/`drill import`: 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; or,
+# for import, read column A back out of an existing tab.
+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
+
+  # Reads column A back out of an existing tab (ignoring any other
+  # columns, e.g. show counts from an older export), skipping blank cells.
+  def self.read_column(spreadsheet_id, sheet_name, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}/values/#{encoded_range(sheet_name)}"
+    data = handle_response(Lexdrill::HTTPClient.json_get(url, headers: auth_header(access_token)))
+    data.fetch("values", []).filter_map { |row| row[0]&.strip }.reject(&:empty?)
+  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.16.0"
 end

data/lib/lexdrill.rb

@@ -9,6 +9,12 @@ require_relative "lexdrill/stats"
 require_relative "lexdrill/word_list"
 require_relative "lexdrill/toggle"
 require_relative "lexdrill/rand"
+require_relative "lexdrill/remote"
+require_relative "lexdrill/oauth_remote"
+require_relative "lexdrill/http_client"
+require_relative "lexdrill/google_auth"
+require_relative "lexdrill/service_account_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.16.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,15 @@ 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/oauth_remote.rb
 - lib/lexdrill/rand.rb
+- lib/lexdrill/remote.rb
+- lib/lexdrill/service_account_auth.rb
+- lib/lexdrill/sheets_client.rb
 - lib/lexdrill/shell_snippet.rb
 - lib/lexdrill/stats.rb
 - lib/lexdrill/toggle.rb