lexdrill 0.21.0 → 0.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03c53271701afc42f6f8b239bd2fb8c85d5d88a55d72c7781573504241d1ad1c
-  data.tar.gz: 231518970e268aa36342feda3885f0771293a0042df918c28b17a63a136ab001
+  metadata.gz: 15b139f554503da2fe92b647d869ffa88bdbe8a7d73e3ce9af8a757b93699013
+  data.tar.gz: 4c9e554c485de8f52a503f64a400f95bb1e6f5d2bb6e717d23ea1245f49b3b75
 SHA512:
-  metadata.gz: b1b115d135527fbc032faa1ad8ea63b48708eda8ce9a9ce8501d59f95f315ab191545a4b8d355d0ab54c2b924ee1267a4873239bc779c8e5290e6f76d16d539f
-  data.tar.gz: 3a038930e2e0a901b1d09227bda97588d7eb2073418156c05151e663413cb0f01c20fbf0457335d5386c6ff20c17e629a2d30c070c41167aea1c132f888499a0
+  metadata.gz: 6482d9523500b1b71634c4d11b104dc4612cbe1711f98a0585ff9cbfc80fc9f7bfbb8851eb74824de6e60d081d0cc5e1a912c854a91e3100751b3cb1411cecc0
+  data.tar.gz: 72ad7861817b7f33fefbed9fd723ad1c8f9e57a5af7af28f0320da218b6ee5e41f98c9f6842fc1410b740f1899658a43b0d27dceb520c916244da8281317cdb3

data/README.md

@@ -176,31 +176,36 @@ the default, so it's also the way to undo `random`).
 
 ### 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
+lexdrill can mirror your word list to a tab in a Google Sheet, and pull it
+back. Three independent layers, each a one-time setup:
+
+1. **Auth mode** (`drill remote` / `drill oauth`, no arguments) — *how*
+   you authenticate to Google. A single global choice.
+2. **Workbooks** (`drill wb ...`) — *which* spreadsheets lexdrill knows
+   about, and which one is currently active. You can add as many as you
+   like.
+3. **Sheets** (`drill sh ...`) — *which tab*, within the active workbook,
+   is currently active.
+
+Once all three are set, `drill push`/`drill pull` (no arguments) act on
+whichever workbook + tab are currently active — and `drill add <text>`
+automatically pushes the updated list too, so your local list and the
+sheet stay in sync as you go.
+
+#### Step 1: choose an auth mode
+
+- **`drill remote`** — a **service account** you create yourself. No
+  interactive sign-in, ever; you share each 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
+- **`drill oauth`** — 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/words` —
-useful for editing the list in Sheets and pulling changes back down, or
-seeding a fresh machine from an existing sheet.
+Whichever you pick applies to every workbook — it's one global setting,
+independent of which spreadsheet is active.
 
-#### Option A: service account (`drill remote`)
+##### 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
@@ -211,7 +216,7 @@ a real secret you must keep local.
    **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
+   roles — it doesn't need any, since access comes from sharing each
    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
@@ -219,22 +224,21 @@ a real secret you must keep local.
    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
+   field in the downloaded JSON). Share each spreadsheet you want lexdrill
+   to use with this email (**Share** → paste it → grant **Editor** access
+   → uncheck "Notify people" → Share).
+5. Save the downloaded key file to `~/.drill/gcp-service-account.json` on
    your machine (`drill` reads it from that fixed path; 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
+drill remote
 ```
 
 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`)
+##### 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
@@ -258,21 +262,69 @@ personal refresh token, generated only after you interactively approve.
    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
+   refresh-token expiry for some scopes. If `drill push` 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
+drill oauth
+```
+
+The first call that needs a token prints a URL and a short code — visit
+it, sign in with the Google account that has edit access to your
+spreadsheets, and approve. Every call after that is silent (the cached
+token refreshes itself automatically).
+
+#### Step 2: add and switch between workbooks
+
+```bash
+drill wb add 'https://docs.google.com/spreadsheets/d/1opBP4APL5SUvepm9qwjIYRNtDZdoY1Ee87F5PWdxaMg/edit'
+drill wb
+```
+
+`drill wb add <url>` fetches the spreadsheet's own title via the API and
+uses that as its name — no need to type one. The very first workbook you
+add becomes active automatically; adding more doesn't switch you away
+from whichever is currently active. `drill wb` (or `drill wb index`, same
+thing) lists every known workbook, marking the active one with the drill
+sign (⟳); `drill wb use <name>` switches; `drill wb remove <name>` forgets
+one.
+
+#### Step 3: add and switch between tabs
+
+```bash
+drill sh
+drill sh use Sheet1
+```
+
+`drill sh` (or `drill sh index`) lists the tabs in the active workbook,
+marking the active one with the drill sign (⟳). `drill sh use <name>`
+switches to a tab **and immediately pulls it** — replacing your local
+word list with that tab's column A. `drill sh add <name>` creates a new,
+empty tab (and makes it active if no tab was selected yet); `drill sh
+remove <name>` deletes one — this is
+real and permanent, so double-check the name.
+
+#### Staying in sync
+
+Once a workbook and tab are both active:
+
+```bash
+drill push   # overwrite the active tab with your current word list
+drill pull   # replace your word list with the active tab's column A
+drill add some new phrase   # appends locally, then pushes automatically
+drill open   # opens the active tab in your browser
 ```
 
-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).
+`push` always **overwrites** the active tab with the current word list,
+one phrase per row, so it stays an exact mirror even if the list shrinks.
+`pull` is the reverse: it reads column A (ignoring any other columns,
+like an old push's show counts) and **replaces** your local
+`~/.drill/words`. `drill add` never fails because of a sync problem —
+if the push fails (no network, tab renamed, etc.) it just warns on
+stderr; the word is still added locally either way.
 
 ### Commands
 
@@ -280,20 +332,20 @@ itself automatically).
 |---|---|
 | `drill next` | Print the current word and advance |
 | `drill start` / `drill stop` | Pause/resume the automatic per-prompt hook (doesn't affect manual `next`) |
-| `drill inspect` | Show the active config directory, word count, counter value, toggle, beat, rand, color, and remote state |
+| `drill inspect` | Show the active config directory, word count, counter value, toggle, beat, rand, color, auth mode, workbook, and sheet state |
 | `drill hook zsh\|bash` | Print the shell integration snippet (used above) |
 | `drill beat <2-8> <repetitions>` / `drill beat none` | Set or disable the rhythm |
 | `drill polka\|waltz\|rock\|jazz\|jiga\|balkan\|samba <repetitions>` | Shorthand for a fixed loop size (see table above) |
 | `drill color random\|default` | Color each shown word randomly, or by its show count (`default`) |
-| `drill add <text>` | Append a new item to the end of the list |
+| `drill add <text>` | Append a new item to the end of the list; also pushes to the active tab, if one is selected |
 | `drill list` | Show how many times each item has been shown, numbered |
-| `drill open` | Open the list file in `$EDITOR`/`$VISUAL` (falls back to `vi`) |
+| `drill edit` | Open the list file in `$EDITOR`/`$VISUAL` (falls back to `vi`) |
 | `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 wb` | Print a link to whichever workbook (spreadsheet) is currently active (`drill remote`/`drill oauth`) |
-| `drill sheets` | List the tab names in the currently active workbook |
-| `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 |
+| `drill remote` / `drill oauth` | Choose the Google Sheets auth mode: local service account key, or personal OAuth login (global, applies to every workbook) |
+| `drill wb` / `wb index` / `add <url>` / `remove <name>` / `use <name>` | List (bare `drill wb` is an alias for `wb index`)/add/forget/switch known workbooks; `add` names the workbook after the spreadsheet's own title; the active one is marked with the drill sign |
+| `drill sh` / `sh index` / `add <name>` / `remove <name>` / `use <name>` | List (bare `drill sh` is an alias for `sh index`)/create/delete/switch tabs in the active workbook; `use` also pulls the tab's contents; the active one is marked with the drill sign |
+| `drill open` | Open the active tab in your default browser |
+| `drill push` | Overwrite the active tab with the current word list text |
+| `drill pull` | Replace the local word list with column A of the active tab |

data/lib/lexdrill/auth_mode.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Global "how to authenticate to Google Sheets" choice: "remote" (service
+# account, no interactive sign-in) or "oauth" (personal Google login).
+# Independent of which workbook is active — see Lexdrill::Workbooks for
+# that. Set via `drill remote` / `drill oauth` (no arguments).
+module Lexdrill::AuthMode
+  PATH = Lexdrill::Config.path("auth-mode")
+  REMOTE = "remote"
+  OAUTH = "oauth"
+  VALID = [REMOTE, OAUTH].freeze
+
+  def self.set(mode)
+    File.write(PATH, mode)
+  end
+
+  def self.current
+    return nil unless File.exist?(PATH)
+
+    value = File.read(PATH).strip
+    VALID.include?(value) ? value : nil
+  end
+end

data/lib/lexdrill/browser.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+# Opens a URL in the system's default browser, cross-platform, for
+# `drill open`.
+module Lexdrill::Browser
+  def self.open(url)
+    system(*open_command(url), out: File::NULL, err: File::NULL)
+  end
+
+  def self.open_command(url)
+    case RbConfig::CONFIG["host_os"]
+    when /darwin/ then ["open", url]
+    when /mswin|mingw|cygwin/ then ["cmd", "/c", "start", "", url]
+    else ["xdg-open", url]
+    end
+  end
+  private_class_method :open_command
+end

data/lib/lexdrill/cli.rb

@@ -14,16 +14,17 @@ class Lexdrill::CLI
     run_color: %w[color],
     run_add: %w[add],
     run_list: %w[list],
-    run_open: %w[open],
+    run_edit: %w[edit],
     run_stats: %w[stats],
     run_rand: %w[rand],
     run_go: %w[go],
     run_remote: %w[remote],
     run_oauth: %w[oauth],
     run_wb: %w[wb],
-    run_sheets: %w[sheets],
-    run_export: %w[export],
-    run_import: %w[import]
+    run_sh: %w[sh],
+    run_open: %w[open],
+    run_push: %w[push],
+    run_pull: %w[pull]
   }.freeze
 
   def self.start(argv = ARGV)
@@ -69,21 +70,28 @@ class Lexdrill::CLI
         drill polka|waltz|rock|jazz|jiga|balkan|samba [repetitions]
                         Shorthand for a fixed loop size (2 through 8, in order)
         drill color random|default   Color each word randomly, or by its show count (default)
-        drill add <text>   Append a new item to the end of the list
+        drill add <text>   Append a new item to the list (and push, if a sheet is selected)
         drill list         Show how many times each item has been shown
-        drill open         Open the list file in $EDITOR/$VISUAL (falls back to vi)
+        drill edit         Open the list file in $EDITOR/$VISUAL (falls back to vi)
         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 remote                Use a local service account key for Google Sheets auth
                                     (~/.drill/gcp-service-account.json) — no interactive sign-in
-        drill oauth <url>           Set the Google Sheet used by the OAuth (personal-login) flow
-        drill wb                    Print a link to the currently active workbook (spreadsheet)
-        drill sheets                List the tab names in the currently active workbook
-        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
+        drill oauth                  Use your personal Google login for Google Sheets auth
+        drill wb                     Alias for drill wb index
+        drill wb index               List known workbooks (name and URL)
+        drill wb add <url>           Add a workbook by URL (named after its own title)
+        drill wb remove <name>       Forget a workbook
+        drill wb use <name>          Switch the active workbook
+        drill sh                     Alias for drill sh index
+        drill sh index               List the tabs in the active workbook
+        drill sh add <name>          Create a new tab
+        drill sh remove <name>       Delete a tab
+        drill sh use <name>          Switch the active tab (pulls its contents)
+        drill open                   Open the active tab in your browser
+        drill push                   Push the word list text to the active tab (overwrites it)
+        drill pull                   Replace the local word list with the active tab's column A
     HELP
     0
   end
@@ -216,15 +224,34 @@ class Lexdrill::CLI
     1
   end
 
+  # Appends locally, then opportunistically pushes the updated list to the
+  # active tab if one is selected — a failed push is reported but doesn't
+  # change the exit code, since the local add always succeeds regardless.
   def run_add
     text = argv[1..].join(" ")
     return print_add_usage if text.empty?
 
     File.open(Lexdrill::WordList::PATH, "a", encoding: "UTF-8") { |file| file.puts(text) }
     puts "added: #{text}"
+    push_after_add
     0
   end
 
+  def push_after_add
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    sheet_name = Lexdrill::Workbooks.current_sheet
+    return unless spreadsheet_id && sheet_name
+
+    token = current_token
+    return unless token
+
+    Lexdrill::WordList.instance_variable_set(:@words, nil)
+    perform_push(spreadsheet_id, sheet_name, token)
+  rescue Lexdrill::GoogleAuth::AuthError, Lexdrill::ServiceAccountAuth::AuthError,
+         Lexdrill::SheetsClient::ApiError, Lexdrill::HTTPClient::NetworkError => error
+    warn "drill: added locally, but couldn't push to #{sheet_name.inspect}: #{error.message}"
+  end
+
   def print_add_usage
     warn "usage: drill add <text>"
     1
@@ -239,7 +266,7 @@ class Lexdrill::CLI
     0
   end
 
-  def run_open
+  def run_edit
     editor_cmd = (ENV["VISUAL"] || ENV["EDITOR"] || "vi").split
     system(*editor_cmd, Lexdrill::WordList::PATH) ? 0 : 1
   end
@@ -299,74 +326,170 @@ class Lexdrill::CLI
   end
 
   def run_remote
-    url = argv[1]
-    return print_remote_usage unless url
+    Lexdrill::AuthMode.set(Lexdrill::AuthMode::REMOTE)
+    puts "auth mode set: remote (service account)"
+    0
+  end
 
-    Lexdrill::Remote.set(url)
-    puts "remote spreadsheet set: #{Lexdrill::Remote.spreadsheet_id}"
+  def run_oauth
+    Lexdrill::AuthMode.set(Lexdrill::AuthMode::OAUTH)
+    puts "auth mode set: oauth (personal login)"
     0
-  rescue ArgumentError
-    print_invalid_remote_url(url)
   end
 
-  def print_remote_usage
-    warn "usage: drill remote <google-sheets-url>"
+  def current_token
+    case Lexdrill::AuthMode.current
+    when Lexdrill::AuthMode::REMOTE then Lexdrill::ServiceAccountAuth.fetch_token!
+    when Lexdrill::AuthMode::OAUTH then Lexdrill::GoogleAuth.ensure_token!
+    end
+  end
+
+  def print_no_auth_mode
+    warn "drill: no auth mode configured; run `drill remote` (service account) or `drill oauth` (personal login) first"
     1
   end
 
-  def print_invalid_remote_url(url)
-    warn "drill: could not find a spreadsheet id in #{url.inspect}"
+  def run_wb
+    case argv[1]
+    when nil, "index" then run_wb_index
+    when "add" then run_wb_add
+    when "remove" then run_wb_remove
+    when "use" then run_wb_use
+    else print_wb_usage
+    end
+  end
+
+  def print_wb_usage
+    warn "usage: drill wb index|add <url>|remove <name>|use <name>"
     1
   end
 
-  def run_oauth
-    url = argv[1]
-    return print_oauth_usage unless url
+  def run_wb_index
+    names = Lexdrill::Workbooks.names
+    return print_no_workbooks if names.empty?
 
-    Lexdrill::OauthRemote.set(url)
-    puts "oauth spreadsheet set: #{Lexdrill::OauthRemote.spreadsheet_id}"
+    current = Lexdrill::Workbooks.current_name
+    names.each { |name| puts "#{current_marker(name == current)} #{name}  #{Lexdrill::Workbooks.url_for(name)}" }
     0
-  rescue ArgumentError
-    print_invalid_oauth_url(url)
   end
 
-  def print_oauth_usage
-    warn "usage: drill oauth <google-sheets-url>"
+  # A painted drill sign for the current item, or a blank space otherwise —
+  # used by `drill wb`/`drill sh` to mark the active workbook/sheet.
+  def current_marker(is_current)
+    is_current ? Lexdrill::Colorizer.paint_yellow(Lexdrill::LineFormatter::SEPARATOR) : " "
+  end
+
+  def print_no_workbooks
+    warn "drill: no workbooks configured; run `drill wb add <url>`"
     1
   end
 
-  def print_invalid_oauth_url(url)
-    warn "drill: could not find a spreadsheet id in #{url.inspect}"
+  def run_wb_add
+    url = argv[2]
+    return print_wb_add_usage unless url
+
+    spreadsheet_id = Lexdrill::Workbooks.extract_id(url)
+    return print_invalid_wb_url(url) unless spreadsheet_id
+
+    add_workbook(spreadsheet_id)
+  rescue Lexdrill::GoogleAuth::AuthError, Lexdrill::ServiceAccountAuth::AuthError => error
+    warn "drill: #{error.message}"
+    1
+  rescue Lexdrill::SheetsClient::ApiError => error
+    print_sheets_api_error(error)
+  rescue Lexdrill::HTTPClient::NetworkError => error
+    warn "drill: network error talking to Google (#{error.message})"
     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
-    kind = Lexdrill::RemoteTarget.kind
-    spreadsheet_id = Lexdrill::RemoteTarget.spreadsheet_id
-    return unless spreadsheet_id
+  def add_workbook(spreadsheet_id)
+    token = current_token
+    return print_no_auth_mode unless token
+
+    title = Lexdrill::SheetsClient.spreadsheet_title(spreadsheet_id, token)
+    return print_wb_name_taken(title) if Lexdrill::Workbooks.names.include?(title)
 
-    [spreadsheet_id, kind == :remote ? Lexdrill::ServiceAccountAuth.fetch_token! : Lexdrill::GoogleAuth.ensure_token!]
+    Lexdrill::Workbooks.add(title, spreadsheet_id)
+    puts "workbook added: #{title.inspect}"
+    0
   end
 
-  def run_wb
-    url = Lexdrill::RemoteTarget.url
-    return print_no_remote unless url
+  def print_wb_add_usage
+    warn "usage: drill wb add <url>"
+    1
+  end
 
-    puts url
+  def print_invalid_wb_url(url)
+    warn "drill: could not find a spreadsheet id in #{url.inspect}"
+    1
+  end
+
+  def print_wb_name_taken(title)
+    warn "drill: a workbook named #{title.inspect} is already configured"
+    1
+  end
+
+  def run_wb_remove
+    name = argv[2]
+    return print_wb_remove_usage unless name
+    return print_no_such_workbook(name) unless Lexdrill::Workbooks.remove(name)
+
+    puts "workbook removed: #{name.inspect}"
     0
   end
 
-  def run_sheets
-    target = sheets_target
-    return print_no_remote unless target
+  def print_wb_remove_usage
+    warn "usage: drill wb remove <name>"
+    1
+  end
+
+  def print_no_such_workbook(name)
+    warn "drill: no workbook named #{name.inspect} (see `drill wb index`)"
+    1
+  end
+
+  def run_wb_use
+    name = argv[2]
+    return print_wb_use_usage unless name
+    return print_no_such_workbook(name) unless Lexdrill::Workbooks.use(name)
 
-    spreadsheet_id, token = target
-    Lexdrill::SheetsClient.sheet_titles(spreadsheet_id, token).each { |title| puts title }
+    puts "workbook set: #{name.inspect}"
     0
+  end
+
+  def print_wb_use_usage
+    warn "usage: drill wb use <name>"
+    1
+  end
+
+  def run_sh
+    case argv[1]
+    when nil, "index" then run_sh_index
+    when "add" then run_sh_add
+    when "remove" then run_sh_remove
+    when "use" then run_sh_use
+    else print_sh_usage
+    end
+  end
+
+  def print_sh_usage
+    warn "usage: drill sh index|add <name>|remove <name>|use <name>"
+    1
+  end
+
+  def print_no_workbook_selected
+    warn "drill: no workbook selected; run `drill wb add <url>` or `drill wb use <name>` first"
+    1
+  end
+
+  def run_sh_index
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    return print_no_workbook_selected unless spreadsheet_id
+
+    token = current_token
+    return print_no_auth_mode unless token
+
+    list_sheets(spreadsheet_id, token)
   rescue Lexdrill::GoogleAuth::AuthError, Lexdrill::ServiceAccountAuth::AuthError => error
     warn "drill: #{error.message}"
     1
@@ -377,80 +500,199 @@ class Lexdrill::CLI
     1
   end
 
-  def run_export
-    sheet_name = argv[1]
-    return print_export_usage unless sheet_name
+  def list_sheets(spreadsheet_id, token)
+    current = Lexdrill::Workbooks.current_sheet
+    Lexdrill::SheetsClient.sheet_titles(spreadsheet_id, token).each do |title|
+      puts "#{current_marker(title == current)} #{title}"
+    end
+    0
+  end
+
+  def run_sh_add
+    name = argv[2]
+    return print_sh_add_usage unless name
+
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    return print_no_workbook_selected unless spreadsheet_id
 
-    target = sheets_target
-    return print_no_remote unless target
+    token = current_token
+    return print_no_auth_mode unless token
 
-    perform_export(sheet_name, *target)
+    add_sheet(spreadsheet_id, name, token)
   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)
+    print_sheets_api_error(error, 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}"
+  def add_sheet(spreadsheet_id, name, token)
+    sheet_id = Lexdrill::SheetsClient.add_sheet(spreadsheet_id, name, token)
+    Lexdrill::Workbooks.set_current_sheet(name, sheet_id) unless Lexdrill::Workbooks.current_sheet
+    puts "sheet added: #{name.inspect}"
     0
   end
 
-  def export_rows
-    Lexdrill::WordList.words.map { |word| [word] }
+  def print_sh_add_usage
+    warn "usage: drill sh add <name>"
+    1
   end
 
-  def print_export_usage
-    warn "usage: drill export <sheet-name>"
+  def run_sh_remove
+    name = argv[2]
+    return print_sh_remove_usage unless name
+
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    return print_no_workbook_selected unless spreadsheet_id
+
+    token = current_token
+    return print_no_auth_mode unless token
+
+    remove_sheet(spreadsheet_id, name, token)
+  rescue Lexdrill::GoogleAuth::AuthError, Lexdrill::ServiceAccountAuth::AuthError => error
+    warn "drill: #{error.message}"
+    1
+  rescue Lexdrill::SheetsClient::ApiError => error
+    print_sheets_api_error(error, name)
+  rescue Lexdrill::HTTPClient::NetworkError => error
+    warn "drill: network error talking to Google (#{error.message})"
     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"
+  def remove_sheet(spreadsheet_id, name, token)
+    sheet_id = Lexdrill::SheetsClient.find_sheet_id(spreadsheet_id, name, token)
+    return print_no_such_sheet(name) unless sheet_id
+
+    Lexdrill::SheetsClient.delete_sheet(spreadsheet_id, sheet_id, token)
+    puts "sheet removed: #{name.inspect}"
+    0
+  end
+
+  def print_sh_remove_usage
+    warn "usage: drill sh remove <name>"
     1
   end
 
-  def run_import
-    sheet_name = argv[1]
-    return print_import_usage unless sheet_name
+  def print_no_such_sheet(name)
+    warn "drill: no tab named #{name.inspect} in the current workbook"
+    1
+  end
+
+  def run_sh_use
+    name = argv[2]
+    return print_sh_use_usage unless name
+
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    return print_no_workbook_selected unless spreadsheet_id
 
-    target = sheets_target
-    return print_no_remote unless target
+    token = current_token
+    return print_no_auth_mode unless token
 
-    perform_import(sheet_name, *target)
+    select_sheet(spreadsheet_id, name, token)
   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)
+    print_sheets_api_error(error, 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?
+  def select_sheet(spreadsheet_id, name, token)
+    sheet_id = Lexdrill::SheetsClient.find_sheet_id(spreadsheet_id, name, token)
+    return print_no_such_sheet(name) unless sheet_id
 
-    File.write(Lexdrill::WordList::PATH, "#{words.join("\n")}\n", encoding: "UTF-8")
-    puts "imported #{words.size} word(s) from #{sheet_name.inspect}"
+    Lexdrill::Workbooks.set_current_sheet(name, sheet_id)
+    perform_pull(spreadsheet_id, name, token)
+  end
+
+  def print_sh_use_usage
+    warn "usage: drill sh use <name>"
+    1
+  end
+
+  def run_open
+    url = Lexdrill::Workbooks.current_url
+    return print_no_workbook_selected unless url
+
+    sheet_id = Lexdrill::Workbooks.current_sheet_id
+    Lexdrill::Browser.open(sheet_id ? "#{url}#gid=#{sheet_id}" : url)
+    0
+  end
+
+  def print_no_sheet_selected
+    warn "drill: no sheet selected; run `drill sh use <name>` first"
+    1
+  end
+
+  def run_push
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    return print_no_workbook_selected unless spreadsheet_id
+
+    sheet_name = Lexdrill::Workbooks.current_sheet
+    return print_no_sheet_selected unless sheet_name
+
+    token = current_token
+    return print_no_auth_mode unless token
+
+    perform_push(spreadsheet_id, sheet_name, token)
+  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_push(spreadsheet_id, sheet_name, token)
+    rows = push_rows
+    Lexdrill::SheetsClient.overwrite_sheet(spreadsheet_id, sheet_name, rows, token)
+    puts "pushed #{rows.size} word(s) to #{sheet_name.inspect}"
     0
   end
 
-  def print_import_usage
-    warn "usage: drill import <sheet-name>"
+  def push_rows
+    Lexdrill::WordList.words.map { |word| [word] }
+  end
+
+  def run_pull
+    spreadsheet_id = Lexdrill::Workbooks.current_id
+    return print_no_workbook_selected unless spreadsheet_id
+
+    sheet_name = Lexdrill::Workbooks.current_sheet
+    return print_no_sheet_selected unless sheet_name
+
+    token = current_token
+    return print_no_auth_mode unless token
+
+    perform_pull(spreadsheet_id, sheet_name, token)
+  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_pull(spreadsheet_id, sheet_name, token)
+    words = Lexdrill::SheetsClient.read_column(spreadsheet_id, sheet_name, token)
+    return print_empty_pull(sheet_name) if words.empty?
+
+    File.write(Lexdrill::WordList::PATH, "#{words.join("\n")}\n", encoding: "UTF-8")
+    puts "pulled #{words.size} word(s) from #{sheet_name.inspect}"
+    0
   end
 
-  def print_empty_import(sheet_name)
-    warn "drill: #{sheet_name.inspect} has no data to import"
+  def print_empty_pull(sheet_name)
+    warn "drill: #{sheet_name.inspect} has no data to pull"
     1
   end
 
@@ -458,7 +700,7 @@ class Lexdrill::CLI
     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 404 then warn "drill: spreadsheet not found or not accessible (check `drill wb index`)"
     when 403 then warn "drill: access denied — make sure the spreadsheet is shared with the right account"
     when 400 then print_400_error(message, sheet_name)
     else warn "drill: Google Sheets API error (#{status}): #{message}"

data/lib/lexdrill/inspector.rb

@@ -15,13 +15,18 @@ module Lexdrill::Inspector
       Beat:          #{beat_summary}
       Rand:          #{rand_summary}
       Color:         #{Lexdrill::Color.current}
-      Remote:        #{remote_summary}
+      Auth mode:     #{Lexdrill::AuthMode.current || 'not configured'}
+      Workbook:      #{workbook_summary}
+      Sheet:         #{Lexdrill::Workbooks.current_sheet || 'not selected'}
       Config dir:    #{Lexdrill::Config::DIR}
     REPORT
   end
 
-  def self.remote_summary
-    Lexdrill::RemoteTarget.url || "not configured"
+  def self.workbook_summary
+    name = Lexdrill::Workbooks.current_name
+    return "not selected" unless name
+
+    "#{name} (#{Lexdrill::Workbooks.current_url})"
   end
 
   def self.words_summary

data/lib/lexdrill/sheets_client.rb

@@ -4,10 +4,12 @@ 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
+# `drill push`/`drill pull`: 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.
+# for pull, read column A back out of an existing tab. Also covers
+# workbook/tab management for `drill wb`/`drill sh`: the workbook's title,
+# the list of tab titles, and creating/deleting a tab.
 module Lexdrill::SheetsClient
   BASE_URL = "https://sheets.googleapis.com/v4/spreadsheets"
 
@@ -42,13 +44,27 @@ module Lexdrill::SheetsClient
   end
   private_class_method :find_sheet
 
+  # The sheetId for a tab by title, or nil if no tab has that title —
+  # for `drill sh use`/`drill sh remove`, which need the numeric id (not
+  # just the name) to build a direct link or issue a delete request.
+  def self.find_sheet_id(spreadsheet_id, sheet_name, access_token)
+    find_sheet(spreadsheet_id, sheet_name, access_token)&.[]("sheetId")
+  end
+
+  # Creates a new, empty tab, for `drill sh add`. Returns its sheetId.
   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
+
+  # Deletes a tab by its numeric sheetId, for `drill sh remove`.
+  def self.delete_sheet(spreadsheet_id, sheet_id, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}:batchUpdate"
+    body = { "requests" => [{ "deleteSheet" => { "sheetId" => sheet_id } }] }
+    handle_response(Lexdrill::HTTPClient.json_post(url, body: body, headers: auth_header(access_token)))
+  end
 
   def self.autofit_first_column(spreadsheet_id, sheet_id, access_token)
     url = "#{BASE_URL}/#{spreadsheet_id}:batchUpdate"
@@ -77,13 +93,20 @@ module Lexdrill::SheetsClient
     data.fetch("values", []).filter_map { |row| row[0]&.strip }.reject(&:empty?)
   end
 
-  # The titles of every tab in the workbook, for `drill sheets`.
+  # The titles of every tab in the workbook, for `drill sh index`.
   def self.sheet_titles(spreadsheet_id, access_token)
     url = "#{BASE_URL}/#{spreadsheet_id}?fields=sheets.properties.title"
     data = handle_response(Lexdrill::HTTPClient.json_get(url, headers: auth_header(access_token)))
     data.fetch("sheets", []).map { |sheet| sheet.dig("properties", "title") }
   end
 
+  # The workbook's own title, for naming it automatically in `drill wb add`.
+  def self.spreadsheet_title(spreadsheet_id, access_token)
+    url = "#{BASE_URL}/#{spreadsheet_id}?fields=properties.title"
+    data = handle_response(Lexdrill::HTTPClient.json_get(url, headers: auth_header(access_token)))
+    data.dig("properties", "title")
+  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.21.0"
+  VERSION = "0.24.0"
 end

data/lib/lexdrill/workbooks.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+# Global list of known Google Sheets workbooks (name => spreadsheet id),
+# which one is currently active, and — per workbook — which tab is
+# currently active within it. Lives at ~/.drill/workbooks.json. Names are
+# the spreadsheet's own title (see `drill wb add`), not chosen by hand.
+module Lexdrill::Workbooks
+  PATH = Lexdrill::Config.path("workbooks.json")
+  URL_PATTERN = %r{/spreadsheets/d/([a-zA-Z0-9_-]+)}
+
+  def self.extract_id(url)
+    url[URL_PATTERN, 1]
+  end
+
+  def self.names
+    load.fetch("workbooks").keys
+  end
+
+  def self.add(name, spreadsheet_id)
+    data = load
+    data["workbooks"][name] = { "id" => spreadsheet_id }
+    data["current"] ||= name
+    save(data)
+  end
+
+  def self.remove(name)
+    data = load
+    return false unless data["workbooks"].delete(name)
+
+    data["current"] = nil if data["current"] == name
+    save(data)
+    true
+  end
+
+  def self.use(name)
+    data = load
+    return false unless data["workbooks"].key?(name)
+
+    data["current"] = name
+    save(data)
+    true
+  end
+
+  def self.current_name
+    load["current"]
+  end
+
+  def self.current_id
+    current_entry&.fetch("id")
+  end
+
+  def self.url_for(name)
+    entry = load.fetch("workbooks")[name]
+    entry && "https://docs.google.com/spreadsheets/d/#{entry.fetch('id')}/edit"
+  end
+
+  def self.current_url
+    name = current_name
+    name && url_for(name)
+  end
+
+  def self.set_current_sheet(sheet_name, sheet_id)
+    data = load
+    workbooks = data["workbooks"]
+    name = data["current"]
+    return false unless name && workbooks.key?(name)
+
+    entry = workbooks[name]
+    entry["current_sheet"] = sheet_name
+    entry["current_sheet_id"] = sheet_id
+    save(data)
+    true
+  end
+
+  def self.current_sheet
+    current_entry&.[]("current_sheet")
+  end
+
+  def self.current_sheet_id
+    current_entry&.[]("current_sheet_id")
+  end
+
+  def self.current_entry
+    name = current_name
+    name && load.fetch("workbooks")[name]
+  end
+  private_class_method :current_entry
+
+  def self.load
+    return { "current" => nil, "workbooks" => {} } unless File.exist?(PATH)
+
+    data = JSON.parse(File.read(PATH, encoding: "UTF-8"))
+    data["workbooks"] ||= {}
+    data
+  rescue JSON::ParserError
+    { "current" => nil, "workbooks" => {} }
+  end
+  private_class_method :load
+
+  def self.save(data)
+    File.write(PATH, JSON.generate(data), encoding: "UTF-8")
+  end
+  private_class_method :save
+end

data/lib/lexdrill.rb

@@ -9,9 +9,9 @@ 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/remote_target"
+require_relative "lexdrill/auth_mode"
+require_relative "lexdrill/workbooks"
+require_relative "lexdrill/browser"
 require_relative "lexdrill/http_client"
 require_relative "lexdrill/google_auth"
 require_relative "lexdrill/service_account_auth"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lexdrill
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.24.0
 platform: ruby
 authors:
 - Siarhei Kisliak
@@ -25,7 +25,9 @@ files:
 - bin/drill
 - lexdrill.gemspec
 - lib/lexdrill.rb
+- lib/lexdrill/auth_mode.rb
 - lib/lexdrill/beat.rb
+- lib/lexdrill/browser.rb
 - lib/lexdrill/cli.rb
 - lib/lexdrill/color.rb
 - lib/lexdrill/colorizer.rb
@@ -36,10 +38,7 @@ 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/remote_target.rb
 - lib/lexdrill/service_account_auth.rb
 - lib/lexdrill/sheets_client.rb
 - lib/lexdrill/shell_snippet.rb
@@ -47,6 +46,7 @@ files:
 - lib/lexdrill/toggle.rb
 - lib/lexdrill/version.rb
 - lib/lexdrill/word_list.rb
+- lib/lexdrill/workbooks.rb
 homepage: https://github.com/kislak/lexdrill
 licenses:
 - MIT

data/lib/lexdrill/oauth_remote.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# Global "which Google Sheet to export to via the OAuth device-flow login"
-# setting. Stored 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 = Lexdrill::Config.path("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,31 +0,0 @@
-# frozen_string_literal: true
-
-# Global "which Google Sheet to export to via a service account" setting.
-# Stored 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 = Lexdrill::Config.path("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_target.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# Resolves which configured Google Sheet target (drill remote / drill
-# oauth) is currently active — whichever was set more recently — so
-# `drill export`/`drill import`, `drill sheet`, and `drill inspect` all
-# agree on a single answer.
-module Lexdrill::RemoteTarget
-  def self.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 self.spreadsheet_id
-    case kind
-    when :remote then Lexdrill::Remote.spreadsheet_id
-    when :oauth then Lexdrill::OauthRemote.spreadsheet_id
-    end
-  end
-
-  def self.url
-    id = spreadsheet_id
-    "https://docs.google.com/spreadsheets/d/#{id}/edit" if id
-  end
-
-  def self.newer?(path, other_path)
-    File.mtime(path) >= File.mtime(other_path)
-  end
-  private_class_method :newer?
-end