lexdrill 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12866aced5d028c5f5951d0a201a7351090cc27adb617c73e317b80df3dcaa0f
-  data.tar.gz: 2e14d88608088fdbb6bd1a0071171696182deb828b840826bd3e7a7964f1f887
+  metadata.gz: 36e9bb140cbbb757b2c9703b8cd122a9fd62a3faa108c4cc0072755391acb65f
+  data.tar.gz: b3502832141a5b7e751f69c5b6d8e729c640f5896300053b96f99fe068968b73
 SHA512:
-  metadata.gz: 8c8947fc580a75406e2a02b164092d49dc0bf66663ed55f0b5d395374e9f169b6bb330e84cdebedbb0ea91f5af88334c8bfa5f0532699b122b9d29d01eae7d50
-  data.tar.gz: 1b7c635562627735a1f85bc1656398f8782bcfaead000c24be594ade643748e89b2e0993215c853139fce1c3587758640c5b73e43e11b6de9293aedcb85fcf59
+  metadata.gz: f89f5aa67e5ad3170d1cd956a4c0d53ffca66993f5b94ad55a3f9ef6e32bbaa8befb8d522e03506c761826a4273b1f86f72c4e92c2230c6d2c4b2906149bb70b
+  data.tar.gz: ac7a2afdfbdff3fe694b4ec90f30eaa7c418707a9370697033cadabf0d2b389f68f5356404ab62afbff30f685d16316399777721861ffe31c2e95970047d974f

data/README.md

@@ -182,54 +182,103 @@ 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.
+`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. 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)
+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.
-2. **APIs & Services → Library** → search "Google Sheets API" → Enable.
-3. **APIs & Services → OAuth consent screen**: User type **External**;
+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".
-4. **APIs & Services → Credentials → Create Credentials → OAuth client
+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`.
-5. "Testing" publishing status has historically imposed a 7-day
+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.
 
-#### Using it
-
 ```bash
-drill remote 'https://docs.google.com/spreadsheets/d/1opBP4APL5SUvepm9qwjIYRNtDZdoY1Ee87F5PWdxaMg/edit?usp=sharing'
+drill oauth '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.
+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
 
@@ -248,5 +297,7 @@ stats), so it stays an exact mirror even if the list shrinks.
 | `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 |
+| `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

@@ -19,7 +19,9 @@ class Lexdrill::CLI
     run_rand: %w[rand],
     run_go: %w[go],
     run_remote: %w[remote],
-    run_export: %w[export]
+    run_oauth: %w[oauth],
+    run_export: %w[export],
+    run_import: %w[import]
   }.freeze
 
   def self.start(argv = ARGV)
@@ -71,9 +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 to export to (global, ~/.drill.remote)
+        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); first run opens a one-time Google device-flow sign-in
+                                    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
@@ -311,13 +317,58 @@ class Lexdrill::CLI
     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
-    return print_no_remote unless Lexdrill::Remote.configured?
 
-    perform_export(sheet_name)
-  rescue Lexdrill::GoogleAuth::AuthError => error
+    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
@@ -327,10 +378,9 @@ class Lexdrill::CLI
     1
   end
 
-  def perform_export(sheet_name)
-    token = Lexdrill::GoogleAuth.ensure_token!
+  def perform_export(sheet_name, spreadsheet_id, token)
     rows = export_rows
-    Lexdrill::SheetsClient.overwrite_sheet(Lexdrill::Remote.spreadsheet_id, sheet_name, rows, token)
+    Lexdrill::SheetsClient.overwrite_sheet(spreadsheet_id, sheet_name, rows, token)
     puts "exported #{rows.size} word(s) to #{sheet_name.inspect}"
     0
   end
@@ -345,7 +395,45 @@ class Lexdrill::CLI
   end
 
   def print_no_remote
-    warn "drill: no remote spreadsheet configured; run `drill remote <url>` first"
+    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
 
@@ -353,8 +441,8 @@ class Lexdrill::CLI
     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 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

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

@@ -1,7 +1,11 @@
 # 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.
+# 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_-]+)}

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

@@ -4,9 +4,10 @@ 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.
+# `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"
 
@@ -68,6 +69,14 @@ module Lexdrill::SheetsClient
     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

data/lib/lexdrill/version.rb

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

data/lib/lexdrill.rb

@@ -10,8 +10,10 @@ 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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lexdrill
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Siarhei Kisliak
@@ -36,8 +36,10 @@ files:
 - 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