copyhub-cli 1.0.1 → 1.0.4

package/.env.example

@@ -1,4 +1,5 @@
-# Copy to .env and fill in values. CopyHub reads .env when you run the CLI from the current directory.
+# Copy to `.env` (project folder), `~/.copyhub/.env`, or both. CopyHub merges these without relying on cwd alone:
+# package dir `.env` → ~/.copyhub/.env → current working directory `.env` (later wins). Shell-exported vars always win.
 #
 # Google Cloud Console → APIs: enable "Google Sheets API" on the SAME project as your OAuth client ID
 # (if sync fails with project=..., open the Enable link in the log or Library → Google Sheets API → Enable).
@@ -10,6 +11,7 @@
 # copyhub start opens the Electron overlay by default; set to 1 for clipboard + Sheet only:
 # COPYHUB_START_NO_OVERLAY=1
 
+# OAuth Client ID / Secret: optional here — running copyhub login opens a browser wizard that saves them to ~/.copyhub/config.json instead.
 COPYHUB_GOOGLE_CLIENT_ID=
 COPYHUB_GOOGLE_CLIENT_SECRET=
 COPYHUB_OAUTH_REDIRECT_PORT=19999

package/README.md

@@ -45,6 +45,68 @@ Or run without linking:
 node src/cli.js <command>
 ```
 
+## Updating
+
+Your settings (`~/.copyhub/config.json`, tokens, history) are kept when you upgrade the CLI.
+
+**Recommended:** stop the background daemon before upgrading so Electron can reinstall cleanly; after upgrading start again:
+
+```bash
+copyhub stop
+```
+
+*(Skip `stop` if you only run `--foreground` or `overlay` and nothing is in the background.)*
+
+### Global install (`npm install -g copyhub-cli`)
+
+Check what npm considers latest vs what you have:
+
+```bash
+npm view copyhub-cli version
+```
+
+Upgrade to the latest published release:
+
+```bash
+npm install -g copyhub-cli@latest
+```
+
+Alternatively:
+
+```bash
+npm update -g copyhub-cli
+```
+
+Restart CopyHub:
+
+```bash
+copyhub start
+```
+
+To see the installed package version: `npm list -g copyhub-cli --depth=0`.
+
+### From source
+
+Pull latest commits and reinstall modules:
+
+```bash
+copyhub stop
+git pull
+npm install
+```
+
+If you previously ran **`npm link`**, linking stays tied to this folder — after `npm install` you usually **do not** need to link again unless npm warns otherwise:
+
+```bash
+npm link
+```
+
+Then:
+
+```bash
+copyhub start
+```
+
 ## Google Cloud setup
 
 1. Enable **[Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)** on your OAuth project.
@@ -54,13 +116,13 @@ node src/cli.js <command>
    http://127.0.0.1:19999/oauth2callback
    ```
 
-3. Copy `.env.example` to `.env` and set:
+3. Provide OAuth credentials in **any one** of these ways:
 
-   - `COPYHUB_GOOGLE_CLIENT_ID`
-   - `COPYHUB_GOOGLE_CLIENT_SECRET`
-   - Optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**)
+   - **Recommended for first setup:** run **`copyhub login`** with no secrets configured — your browser opens a **localhost wizard** where you paste **Client ID** and **Client secret** (the same values as `COPYHUB_GOOGLE_CLIENT_ID` / `COPYHUB_GOOGLE_CLIENT_SECRET`); they are stored in `~/.copyhub/config.json`.
 
-Alternatively, store credentials in `~/.copyhub/config.json` via:
+   - Copy `.env.example` to **`~/.copyhub/.env`** and/or a `.env` in your project folder and set `COPYHUB_GOOGLE_CLIENT_ID`, `COPYHUB_GOOGLE_CLIENT_SECRET`, and optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**). This works even with **`npm install -g`** when your shell is not in the repo directory.
+
+   - Or run **`copyhub config`**:
 
 ```bash
 copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREADSHEET_ID>"] [--redirect-port 19999]
@@ -68,13 +130,16 @@ copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREA
 
 ## First run
 
-1. **Login** (opens the browser for OAuth, then a setup page):
+1. **Login** — opens the browser:
 
    ```bash
    copyhub login
    ```
 
-2. On the setup page, enter your **Spreadsheet ID** (from the URL `…/d/<SPREADSHEET_ID>/edit`), choose **platform** (Windows / macOS / Linux) for shortcut hints, set the **overlay accelerator** if you want, and save.
+   - If Client ID / Secret are **not** already in `.env` or `~/.copyhub/config.json`, the first screen collects them (**Google OAuth credentials** page). Submit it to save into config.
+   - After Google sign-in, another setup page asks for **Spreadsheet ID**, **platform**, and optional **overlay shortcut**.
+
+2. On that spreadsheet/setup page, enter your **Spreadsheet ID** (from the URL `…/d/<SPREADSHEET_ID>/edit`), choose **platform** (Windows / macOS / Linux) for shortcut hints, set the **overlay accelerator** if you want, and save.
 
 3. **Start** the background watcher (clipboard + Sheets + overlay by default):
 
@@ -116,7 +181,7 @@ copyhub --help
 | Command | What it does |
 |---------|----------------|
 | `copyhub config` | Writes OAuth client ID/secret (and optional Sheet ID, redirect port) to `~/.copyhub/config.json`. `--client-id` and `--client-secret` are required. |
-| `copyhub login` | Opens browser for Google OAuth, then the setup page (spreadsheet ID, platform, overlay shortcut). |
+| `copyhub login` | Opens browser: localhost wizard for Client ID/secret if missing, then Google OAuth, then spreadsheet/platform setup. |
 | `copyhub logout` | Deletes saved OAuth tokens (`~/.copyhub/tokens.json`). |
 | `copyhub status` | Prints OAuth config source, sheet target, tokens, overlay settings, and whether the background daemon is running. |
 | `copyhub start` | Starts clipboard watcher + optional Sheets sync + Electron overlay in the **background** (closing the terminal does not stop it). Only one instance at a time. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copyhub-cli",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "CopyHub — clipboard, local history, Google Sheets sync (OAuth). Windows, macOS, Linux.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import 'dotenv/config';
+import { loadCopyhubEnv } from './load-env.js';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { program } from 'commander';
@@ -31,6 +31,9 @@ import {
 import { killDaemonTree } from './stop-process.js';
 import { ensureDir } from './storage.js';
 import { runCopyhubDaemon } from './start-daemon-logic.js';
+import { wipeCopyhubDirectory } from './wipe-data.js';
+
+loadCopyhubEnv();
 
 const CLI_JS = fileURLToPath(new URL('./cli.js', import.meta.url));
 
@@ -72,7 +75,7 @@ program
 program
   .command('login')
   .description(
-    `Google sign-in (OAuth Sheets), then Spreadsheet ID setup page — port ${DEFAULT_OAUTH_REDIRECT_PORT} or ${ENV_OAUTH_REDIRECT_PORT}`,
+    `OAuth Sheets flow (opens browser). If Client ID/Secret are missing, a localhost wizard saves them first — callback port ${DEFAULT_OAUTH_REDIRECT_PORT} or ${ENV_OAUTH_REDIRECT_PORT}`,
   )
   .action(async () => {
     await runLoginFlow();
@@ -86,6 +89,35 @@ program
     console.log(`Removed tokens: ${TOKENS_PATH}`);
   });
 
+program
+  .command('reset')
+  .description(
+    'Stop background daemon if running; delete ~/.copyhub entirely (config, tokens, history, run state). Requires --yes',
+  )
+  .option('--yes', 'Required confirmation flag (destructive)')
+  .action(async (opts) => {
+    if (!opts.yes) {
+      console.error(
+        'Refusing to wipe without --yes. Deletes ~/.copyhub (Windows: %USERPROFILE%\\.copyhub). Example: copyhub reset --yes',
+      );
+      process.exit(1);
+    }
+    pruneStaleRunState();
+    const s = readRunState();
+    if (s?.pid && isPidAlive(s.pid)) {
+      killDaemonTree(s.pid);
+    }
+    try {
+      await wipeCopyhubDirectory();
+    } catch (e) {
+      console.error((/** @type {Error} */ (e)).message || String(e));
+      process.exit(1);
+    }
+    console.log(`Removed CopyHub data directory: ${DIR}`);
+    console.log('.env is not changed — remove OAuth vars there if you want.');
+    console.log('If an overlay window was open separately, close it manually.');
+  });
+
 program
   .command('overlay')
   .description(
@@ -163,7 +195,7 @@ program
     if (!cfg) {
       console.log('OAuth config: missing');
       console.log(
-        `  Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env (see .env.example), or run: copyhub config`,
+        `  Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env (see .env.example), run copyhub config, or copyhub login (browser wizard)`,
       );
     } else {
       const srcLabel =
@@ -333,6 +365,7 @@ program
   .action(() => {
     console.log(`copyhub config [--client-id ID] [--client-secret SEC] [--redirect-port P] [--sheet-id ID]
 copyhub login     | copyhub logout | copyhub status
+copyhub reset --yes   (delete ~/.copyhub — stop daemon first is recommended)
 copyhub start [--no-sheet] [--no-overlay] [--foreground]
       Default runs in background (terminal can close). Single instance — second start is blocked.
 copyhub list (ls) | copyhub stop

package/src/config.js

@@ -22,6 +22,26 @@ function parseRedirectPortFromEnv() {
   return n;
 }
 
+/**
+ * Port for the OAuth HTTP listener (env wins, then saved config, then default).
+ * Does not require Client ID / Secret (used before credential bootstrap).
+ */
+export function resolveOAuthListenPort() {
+  const envPort = parseRedirectPortFromEnv();
+  if (envPort != null) return envPort;
+  if (existsSync(CONFIG_PATH)) {
+    try {
+      const j = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+      if (typeof j.redirectPort === 'number' && Number.isFinite(j.redirectPort)) {
+        return j.redirectPort;
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+  return DEFAULT_OAUTH_REDIRECT_PORT;
+}
+
 /** Both Client ID and Secret come from environment (or .env). */
 export function hasOAuthCredentialsInEnv() {
   const id = process.env[ENV_GOOGLE_CLIENT_ID]?.trim();

package/src/load-env.js

@@ -0,0 +1,39 @@
+import dotenv from 'dotenv';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DIR } from './paths.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Merge `.env` files into `process.env` without overwriting shell-exported vars.
+ * Order (later wins among files only): package directory → ~/.copyhub/.env → cwd.
+ * Fixes global `copyhub login` when cwd has no `.env` (dotenv/config default looks only at cwd).
+ */
+export function loadCopyhubEnv() {
+  const pkgRoot = join(__dirname, '..');
+  const paths = [
+    join(pkgRoot, '.env'),
+    join(DIR, '.env'),
+    join(process.cwd(), '.env'),
+  ];
+
+  /** @type {Record<string, string>} */
+  const merged = {};
+  for (const p of paths) {
+    if (!existsSync(p)) continue;
+    try {
+      const raw = readFileSync(p, 'utf8');
+      Object.assign(merged, dotenv.parse(raw));
+    } catch {
+      /* ignore unreadable or malformed .env */
+    }
+  }
+
+  for (const [key, value] of Object.entries(merged)) {
+    if (process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}

package/src/oauth.js

@@ -8,7 +8,9 @@ import {
   DEFAULT_OAUTH_REDIRECT_PORT,
   ENV_GOOGLE_CLIENT_ID,
   ENV_GOOGLE_CLIENT_SECRET,
+  ENV_OAUTH_REDIRECT_PORT,
   mergeConfigPartial,
+  resolveOAuthListenPort,
   loadSheetSyncTarget,
   loadOverlayAcceleratorFromConfigSync,
   loadOverlayPlatformFromConfigSync,
@@ -34,7 +36,7 @@ export async function getAuthorizedClient() {
   const cfg = await loadConfig();
   if (!cfg) {
     throw new Error(
-      `OAuth is not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} (.env or environment), or run: copyhub config --client-id ID --client-secret SECRET`,
+      `OAuth is not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} (.env or environment), run copyhub config, or copyhub login (browser wizard).`,
     );
   }
   const client = createOAuthClient(cfg);
@@ -75,6 +77,256 @@ function escapeHtml(s) {
     .replace(/'/g, ''');
 }
 
+/**
+ * @param {string} bootstrapToken
+ * @param {number} listenPort
+ */
+function credentialSetupPageHtml(bootstrapToken, listenPort) {
+  const tVal = escapeHtml(bootstrapToken);
+  const callbackUri = `http://127.0.0.1:${listenPort}/oauth2callback`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>CopyHub — Google OAuth credentials</title>
+  <style>
+    :root {
+      --text: #141824;
+      --muted: #5a6272;
+      --line: #e2e8f1;
+      --accent: #2563eb;
+      --accent-soft: #eff6ff;
+      --radius: 14px;
+      --shadow: 0 4px 24px rgba(20, 24, 36, 0.08), 0 1px 3px rgba(20, 24, 36, 0.04);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+      background: linear-gradient(160deg, #e8eef9 0%, #f5f7fb 45%, #eef2f8 100%);
+      color: var(--text);
+      padding: 32px 16px 48px;
+      line-height: 1.55;
+    }
+    .wrap { max-width: 520px; margin: 0 auto; }
+    .brand {
+      font-size: 13px;
+      font-weight: 600;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--accent);
+      margin-bottom: 8px;
+    }
+    h1 { font-size: 1.55rem; font-weight: 700; margin: 0 0 8px; letter-spacing: -0.02em; }
+    .sub { color: var(--muted); font-size: 15px; margin-bottom: 24px; }
+    .card {
+      background: #fff;
+      border-radius: var(--radius);
+      box-shadow: var(--shadow);
+      border: 1px solid rgba(255,255,255,0.8);
+      padding: 26px 24px;
+      margin-bottom: 18px;
+    }
+    label.field-label { display: block; font-weight: 600; font-size: 14px; margin-bottom: 8px; }
+    input[type="password"], input[type="text"] {
+      width: 100%;
+      padding: 12px 14px;
+      font-size: 15px;
+      border: 1px solid var(--line);
+      border-radius: 10px;
+      background: #fafbfd;
+    }
+    input:focus {
+      outline: none;
+      border-color: var(--accent);
+      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.15);
+      background: #fff;
+    }
+    .hint { font-size: 13px; color: var(--muted); margin-top: 10px; line-height: 1.5; }
+    .hint code {
+      font-size: 12px;
+      background: var(--accent-soft);
+      color: #1d4ed8;
+      padding: 2px 7px;
+      border-radius: 6px;
+      font-weight: 500;
+    }
+    button.submit {
+      width: 100%;
+      margin-top: 20px;
+      padding: 14px 20px;
+      font-size: 16px;
+      font-weight: 600;
+      color: #fff;
+      background: linear-gradient(180deg, #3b82f6 0%, #2563eb 100%);
+      border: none;
+      border-radius: 12px;
+      cursor: pointer;
+      box-shadow: 0 2px 8px rgba(37, 99, 235, 0.35);
+    }
+    button.submit:hover { filter: brightness(1.05); }
+    .callback-box {
+      font-size: 13px;
+      padding: 12px 14px;
+      background: linear-gradient(135deg, #f8fafc 0%, #f1f5f9 100%);
+      border-radius: 10px;
+      border: 1px solid var(--line);
+      word-break: break-all;
+    }
+  </style>
+</head>
+<body>
+  <div class="wrap">
+    <div class="brand">CopyHub</div>
+    <h1>Google Cloud OAuth</h1>
+    <p class="sub">Paste your OAuth 2.0 Client ID and Client Secret (same as <code>${ENV_GOOGLE_CLIENT_ID}</code> / <code>${ENV_GOOGLE_CLIENT_SECRET}</code> in <code>.env</code>). Stored in <code>~/.copyhub/config.json</code>.</p>
+
+    <div class="card">
+      <p class="hint" style="margin-top:0;"><strong>Authorized redirect URI</strong> in Google Cloud Console must include:</p>
+      <div class="callback-box"><code>${escapeHtml(callbackUri)}</code></div>
+      <p class="hint">Port comes from <code>${ENV_OAUTH_REDIRECT_PORT}</code> (currently <strong>${listenPort}</strong>) or your saved config.</p>
+    </div>
+
+    <form method="POST" action="/credentials">
+      <input type="hidden" name="t" value="${tVal}" />
+      <div class="card">
+        <label class="field-label" for="cid">Client ID</label>
+        <input id="cid" type="text" name="clientId" autocomplete="off" spellcheck="false" required />
+        <label class="field-label" for="csec" style="margin-top:16px;">Client secret</label>
+        <input id="csec" type="password" name="clientSecret" autocomplete="new-password" spellcheck="false" required />
+      </div>
+      <button type="submit" class="submit">Save and continue to Google sign-in</button>
+    </form>
+  </div>
+</body>
+</html>`;
+}
+
+const credentialSavedHtml = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><title>CopyHub</title>
+<style>
+body{font-family:system-ui,sans-serif;min-height:100vh;margin:0;display:flex;align-items:center;justify-content:center;background:linear-gradient(160deg,#e8eef9,#f5f7fb);padding:24px;}
+.box{background:#fff;padding:32px 36px;border-radius:16px;box-shadow:0 8px 32px rgba(20,24,36,.1);max-width:420px;text-align:center;line-height:1.65;color:#141824;}
+.box h2{margin:0 0 12px;font-size:1.25rem;}
+.box p{margin:.6rem 0;color:#5a6272;font-size:15px;}
+.box code{background:#eff6ff;color:#1d4ed8;padding:2px 8px;border-radius:6px;font-size:13px;}
+</style></head>
+<body><div class="box"><h2>Credentials saved</h2>
+<p>The login flow will open Google next (this tab can stay open).</p></div></body></html>`;
+
+/**
+ * Localhost wizard when Client ID / Secret are missing from env and config file.
+ * @returns {Promise<void>}
+ */
+async function runCredentialBootstrap() {
+  const listenPort = resolveOAuthListenPort();
+  await new Promise((resolve, reject) => {
+    /** @type {string | null} */
+    let bootstrapToken = randomBytes(24).toString('hex');
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      server.close(() => resolve(undefined));
+    };
+
+    const server = createServer(async (req, res) => {
+      try {
+        if (!req.url) {
+          res.writeHead(400);
+          res.end('Bad request');
+          return;
+        }
+        const u = new URL(req.url, `http://127.0.0.1:${listenPort}`);
+
+        if (u.pathname === '/credentials' && req.method === 'GET') {
+          const t = u.searchParams.get('t');
+          if (!bootstrapToken || t !== bootstrapToken) {
+            res.writeHead(403, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<p>Invalid session. Run <code>copyhub login</code> again.</p>');
+            return;
+          }
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(credentialSetupPageHtml(bootstrapToken, listenPort));
+          return;
+        }
+
+        if (u.pathname === '/credentials' && req.method === 'POST') {
+          let body = '';
+          try {
+            body = await readRequestBody(req);
+          } catch {
+            res.writeHead(413);
+            res.end('Payload too large');
+            return;
+          }
+          const params = new URLSearchParams(body);
+          const t = params.get('t');
+          if (!bootstrapToken || t !== bootstrapToken) {
+            res.writeHead(403);
+            res.end('Forbidden');
+            return;
+          }
+          const clientId = (params.get('clientId') || '').trim();
+          const clientSecret = (params.get('clientSecret') || '').trim();
+          if (!clientId || !clientSecret) {
+            res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<p>Client ID and Client secret are required.</p>');
+            return;
+          }
+          try {
+            await mergeConfigPartial({ clientId, clientSecret });
+          } catch {
+            res.writeHead(500, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end('<p>Could not write config. Check write permissions on ~/.copyhub/</p>');
+            return;
+          }
+          bootstrapToken = null;
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(credentialSavedHtml);
+          setTimeout(finish, 400);
+          return;
+        }
+
+        res.writeHead(404);
+        res.end('Not found');
+      } catch (e) {
+        res.writeHead(500);
+        res.end('Server error');
+        server.close(() => reject(/** @type {Error} */ (e)));
+      }
+    });
+
+    const idleMs = 20 * 60 * 1000;
+    const idleTimer = setTimeout(() => {
+      if (!settled) {
+        console.warn('Credential setup idle timeout (20 minutes).');
+        finish();
+      }
+    }, idleMs);
+    server.on('close', () => clearTimeout(idleTimer));
+
+    server.on('error', (err) => {
+      if (!settled) reject(err);
+    });
+
+    server.listen(listenPort, '127.0.0.1', async () => {
+      const credUrl = `http://127.0.0.1:${listenPort}/credentials?t=${encodeURIComponent(bootstrapToken)}`;
+      console.log('Opening browser for Google OAuth credentials (localhost wizard)...');
+      console.log(`If it does not open: ${credUrl}`);
+      try {
+        await open(credUrl);
+      } catch {
+        console.log('Open this URL manually:');
+        console.log(credUrl);
+      }
+    });
+  });
+}
+
 /** Shortcut presets (Electron Accelerator) per platform — embedded as JSON in the setup page. */
 const PLATFORM_PRESETS = {
   win: [
@@ -423,10 +675,25 @@ body{font-family:system-ui,sans-serif;min-height:100vh;margin:0;display:flex;ali
  * @returns {Promise<void>}
  */
 export async function runLoginFlow() {
-  const cfg = await loadConfig();
+  let cfg = await loadConfig();
+  if (!cfg) {
+    const listenPort = resolveOAuthListenPort();
+    try {
+      await runCredentialBootstrap();
+    } catch (e) {
+      const code = /** @type {NodeJS.ErrnoException} */ (e)?.code;
+      if (code === 'EADDRINUSE') {
+        throw new Error(
+          `Port ${listenPort} is already in use. Stop the other process or set ${ENV_OAUTH_REDIRECT_PORT} to a free port.`,
+        );
+      }
+      throw /** @type {Error} */ (e);
+    }
+    cfg = await loadConfig();
+  }
   if (!cfg) {
     throw new Error(
-      `Not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env, or run: copyhub config --client-id ... --client-secret ...`,
+      `OAuth is not configured. Set ${ENV_GOOGLE_CLIENT_ID} and ${ENV_GOOGLE_CLIENT_SECRET} in .env, run copyhub config, or complete the browser credential wizard.`,
     );
   }
   const port = cfg.redirectPort ?? DEFAULT_OAUTH_REDIRECT_PORT;

package/src/sheet-overlay-history.js

@@ -0,0 +1,79 @@
+import { google } from 'googleapis';
+import { getAuthorizedClient } from './oauth.js';
+import { loadSheetSyncTarget } from './config.js';
+import { formatGoogleSheetUserMessage } from './sheet-api-errors.js';
+
+/** @param {unknown} v */
+function cellToString(v) {
+  if (v == null) return '';
+  if (typeof v === 'string') return v;
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (v instanceof Date) return v.toISOString();
+  return String(v);
+}
+
+/** @param {string} tabName */
+function escapeTabName(tabName) {
+  return /[^A-Za-z0-9_]/.test(tabName)
+    ? `'${tabName.replace(/'/g, "''")}'`
+    : tabName;
+}
+
+/** @param {number} daysAgo */
+function overlayDailyTabNameDaysAgo(daysAgo) {
+  const d = new Date();
+  d.setDate(d.getDate() - daysAgo);
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `COPYHUB-${y}-${m}-${day}`;
+}
+
+/**
+ * Clipboard rows from one COPYHUB-YYYY-MM-DD tab (newest timestamps first).
+ * Reads used cells in A:B from row 2 onward (append puts newer rows at the bottom).
+ * @param {number} daysAgo 0 = today
+ * @param {number} [maxRowsCap] Keep only this many newest rows (after sort).
+ */
+export async function fetchOverlayDailyTabRows(daysAgo, maxRowsCap = 500) {
+  const day = Math.min(Math.max(Number(daysAgo), 0), 90);
+  const cap = Math.min(Math.max(Number(maxRowsCap), 1), 2000);
+
+  const target = await loadSheetSyncTarget();
+  if (!target) return [];
+
+  const auth = await getAuthorizedClient();
+  if (!auth.credentials.refresh_token && !auth.credentials.access_token) {
+    return [];
+  }
+
+  const sheets = google.sheets({ version: 'v4', auth });
+  const tab = overlayDailyTabNameDaysAgo(day);
+  const range = `${escapeTabName(tab)}!A2:B`;
+
+  try {
+    const res = await sheets.spreadsheets.values.get({
+      spreadsheetId: target.spreadsheetId,
+      range,
+      valueRenderOption: 'FORMATTED_VALUE',
+    });
+
+    const values = res.data.values ?? [];
+
+    /** @type {Array<{ ts: string, text: string, synced: boolean }>} */
+    const items = [];
+    for (const row of values) {
+      if (!Array.isArray(row) || row.length < 2) continue;
+      const ts = cellToString(row[0]).trim();
+      const text = cellToString(row[1]).trim();
+      if (!text) continue;
+      if (/^(time|thời gian)$/i.test(ts)) continue;
+      items.push({ ts: ts || '', text, synced: true });
+    }
+
+    items.sort((a, b) => (Date.parse(b.ts) || 0) - (Date.parse(a.ts) || 0));
+    return items.slice(0, cap);
+  } catch (e) {
+    throw new Error(formatGoogleSheetUserMessage(e));
+  }
+}

package/src/sheets.js

@@ -7,7 +7,7 @@ import { formatGoogleSheetUserMessage } from './sheet-api-errors.js';
 /**
  * @param {string} tabName
  */
-function a1RangeForTab(tabName) {
+export function a1RangeForTab(tabName) {
   const escaped = /[^A-Za-z0-9_]/.test(tabName)
     ? `'${tabName.replace(/'/g, "''")}'`
     : tabName;