copyhub-cli 1.0.0 → 1.0.3

package/.env.example

@@ -1,24 +1,25 @@
-# Copy to .env and fill in values. CopyHub reads .env when you run the CLI from the current directory.
-#
-# 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).
-#
-# Spreadsheet ID + platform + overlay shortcut: set after copyhub login (web setup page),
-# or copyhub config ... --sheet-id <ID> and edit overlayPlatform / overlayAccelerator in ~/.copyhub/config.json
-# One tab per local calendar day: COPYHUB-YYYY-MM-DD (machine timezone).
-#
-# copyhub start opens the Electron overlay by default; set to 1 for clipboard + Sheet only:
-# COPYHUB_START_NO_OVERLAY=1
-
-COPYHUB_GOOGLE_CLIENT_ID=
-COPYHUB_GOOGLE_CLIENT_SECRET=
-COPYHUB_OAUTH_REDIRECT_PORT=19999
-
-# Overlay accelerator (optional): if set here it OVERRIDES the value saved after copyhub login (config overlayAccelerator).
-COPYHUB_OVERLAY_ACCELERATOR=
-
-# Set to 1 to NOT show the window when overlay starts (open via shortcut / tray only).
-# COPYHUB_OVERLAY_HIDE_ON_START=1
-# Set to 1 so the overlay does not close when clicking outside (default: click outside closes).
-# COPYHUB_OVERLAY_STICKY=1
-# Hide overlay icon from the taskbar: COPYHUB_OVERLAY_SKIP_TASKBAR=1
+# Copy to .env and fill in values. CopyHub reads .env when you run the CLI from the current directory.
+#
+# 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).
+#
+# Spreadsheet ID + platform + overlay shortcut: set after copyhub login (web setup page),
+# or copyhub config ... --sheet-id <ID> and edit overlayPlatform / overlayAccelerator in ~/.copyhub/config.json
+# One tab per local calendar day: COPYHUB-YYYY-MM-DD (machine timezone).
+#
+# 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
+
+# Overlay accelerator (optional): if set here it OVERRIDES the value saved after copyhub login (config overlayAccelerator).
+COPYHUB_OVERLAY_ACCELERATOR=
+
+# Set to 1 to NOT show the window when overlay starts (open via shortcut / tray only).
+# COPYHUB_OVERLAY_HIDE_ON_START=1
+# Set to 1 so the overlay does not close when clicking outside (default: click outside closes).
+# COPYHUB_OVERLAY_STICKY=1
+# Hide overlay icon from the taskbar: COPYHUB_OVERLAY_SKIP_TASKBAR=1

package/README.md

@@ -1,122 +1,219 @@
-# CopyHub
-
-CopyHub watches your **clipboard**, keeps a **local history** under `~/.copyhub/history.jsonl`, optionally syncs copies to **Google Sheets** (one tab per day), and shows an **Electron overlay** so you can browse recent clips quickly.
-
-Runs on **Windows**, **macOS**, and **Linux**.
-
-## Requirements
-
-- **Node.js** ≥ 18
-- A **Google Cloud** project with:
-  - **Google Sheets API** enabled for the *same* project as your OAuth client
-  - **OAuth 2.0 Client** (Desktop app type works well for localhost redirect)
-
-## Installation
-
-From this repository:
-
-```bash
-npm install
-```
-
-Link the CLI globally (optional):
-
-```bash
-npm link
-```
-
-Or run commands with:
-
-```bash
-node src/cli.js <command>
-```
-
-## Google Cloud setup
-
-1. Enable **[Google Sheets API](https://console.cloud.google.com/apis/library/sheets.googleapis.com)** on your OAuth project.
-2. Create **OAuth 2.0 credentials** and add this **Authorized redirect URI** (adjust the port if you change it):
-
-   ```text
-   http://127.0.0.1:19999/oauth2callback
-   ```
-
-3. Copy `.env.example` to `.env` and set:
-
-   - `COPYHUB_GOOGLE_CLIENT_ID`
-   - `COPYHUB_GOOGLE_CLIENT_SECRET`
-   - Optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**)
-
-Alternatively, store credentials in `~/.copyhub/config.json` via:
-
-```bash
-copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREADSHEET_ID>"] [--redirect-port 19999]
-```
-
-## First run
-
-1. **Login** (opens the browser for OAuth, then a setup page):
-
-   ```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.
-
-3. **Start** the background watcher (clipboard + Sheets + overlay by default):
-
-   ```bash
-   copyhub start
-   ```
-
-   You can close the terminal; the process keeps running. Check with `copyhub list` and stop with `copyhub stop`.
-
-### Useful flags and environment variables
-
-| Action | How |
-|--------|-----|
-| Run in terminal (Ctrl+C stops everything) | `copyhub start --foreground` |
-| No Google Sheets | `copyhub start --no-sheet` |
-| No Electron overlay | `copyhub start --no-overlay` or `COPYHUB_START_NO_OVERLAY=1` |
-| Override shortcut | `COPYHUB_OVERLAY_ACCELERATOR` in `.env` (overrides saved config) |
-| Overlay stays open when clicking outside | `COPYHUB_OVERLAY_STICKY=1` |
-
-Run `copyhub --help` or `copyhub commands` for the full command list.
-
-## CLI overview
-
-| Command | Purpose |
-|---------|---------|
-| `copyhub config` | Save OAuth client ID/secret (and optional Sheet ID) to `~/.copyhub/config.json` |
-| `copyhub login` | OAuth flow + setup page (Sheet ID, platform, overlay shortcut) |
-| `copyhub logout` | Remove saved tokens |
-| `copyhub status` | OAuth, Sheet, tokens, overlay platform/shortcut, daemon state |
-| `copyhub start` | Background daemon: clipboard watcher + optional Sheets + overlay |
-| `copyhub list` / `copyhub ls` | Show whether the daemon PID is running |
-| `copyhub stop` | Stop daemon and overlay child |
-| `copyhub overlay` | Launch only the Electron overlay (no clipboard daemon) |
-
-## Data locations
-
-Everything lives under **`~/.copyhub/`** (or `%USERPROFILE%\.copyhub` on Windows):
-
-| File | Contents |
-|------|----------|
-| `config.json` | OAuth credentials (if not only in `.env`), `googleSheetId`, `overlayAccelerator`, `overlayPlatform` |
-| `tokens.json` | OAuth refresh/access tokens |
-| `history.jsonl` | Local clipboard history (JSON Lines) |
-| `run.json` | Daemon PID and metadata (when using `copyhub start` without `--foreground`) |
-
-## Google Sheets layout
-
-- Rows are appended when Sheet sync is enabled and you are logged in.
-- New tabs are created per **local calendar day**, named: **`COPYHUB-YYYY-MM-DD`**.
-
-## Overlay (Electron)
-
-- Global shortcut defaults to **`CommandOrControl+Shift+H`** if nothing else is set (`Ctrl+Shift+H` on Windows/Linux, `⌘⇧H` on macOS-style wording in Electron).
-- **macOS**: you may need to grant **Accessibility** permissions for global shortcuts.
-- Some **`Control+Alt+…`** combinations do not register reliably on Windows; prefer alternatives suggested on the setup page.
-
-## License
-
-MIT — see `package.json`.
+# CopyHub
+
+CopyHub watches your **clipboard**, keeps a **local history** under `~/.copyhub/history.jsonl`, optionally syncs copies to **Google Sheets** (one tab per day), and shows an **Electron overlay** so you can browse recent clips quickly.
+
+Runs on **Windows**, **macOS**, and **Linux**.
+
+## Requirements
+
+- **Node.js** ≥ 18
+- A **Google Cloud** project with:
+  - **Google Sheets API** enabled for the *same* project as your OAuth client
+  - **OAuth 2.0 Client** (Desktop app type works well for localhost redirect)
+
+## Installation
+
+### Install globally (npm)
+
+After the package is published to npm:
+
+```bash
+npm install -g copyhub-cli
+```
+
+Then run `copyhub` from any directory (ensure Node.js ≥ 18 is on your `PATH`).
+
+On Linux/macOS you may need elevated permissions or an npm prefix configured for your user; see [npm docs on global installs](https://docs.npmjs.com/cli/v10/commands/npm-install#global-installation).
+
+### From source (this repository)
+
+From the repository root:
+
+```bash
+npm install
+```
+
+Register the CLI on your machine:
+
+```bash
+npm link
+```
+
+Or run without linking:
+
+```bash
+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.
+2. Create **OAuth 2.0 credentials** and add this **Authorized redirect URI** (adjust the port if you change it):
+
+   ```text
+   http://127.0.0.1:19999/oauth2callback
+   ```
+
+3. Provide OAuth credentials in **any one** of these ways:
+
+   - **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`.
+
+   - Copy `.env.example` to `.env` and set `COPYHUB_GOOGLE_CLIENT_ID`, `COPYHUB_GOOGLE_CLIENT_SECRET`, and optionally `COPYHUB_OAUTH_REDIRECT_PORT` (default **19999**).
+
+   - Or run **`copyhub config`**:
+
+```bash
+copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--sheet-id "<SPREADSHEET_ID>"] [--redirect-port 19999]
+```
+
+## First run
+
+1. **Login** — opens the browser:
+
+   ```bash
+   copyhub login
+   ```
+
+   - 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):
+
+   ```bash
+   copyhub start
+   ```
+
+   You can close the terminal; the process keeps running. Check with `copyhub list` and stop with `copyhub stop`.
+
+### Useful flags and environment variables
+
+| Action | How |
+|--------|-----|
+| Run in terminal (Ctrl+C stops everything) | `copyhub start --foreground` |
+| No Google Sheets | `copyhub start --no-sheet` |
+| No Electron overlay | `copyhub start --no-overlay` or `COPYHUB_START_NO_OVERLAY=1` |
+| Override shortcut | `COPYHUB_OVERLAY_ACCELERATOR` in `.env` (overrides saved config) |
+| Overlay stays open when clicking outside | `COPYHUB_OVERLAY_STICKY=1` |
+
+Run `copyhub --help` or `copyhub commands` for built-in help.
+
+## CLI commands
+
+Quick reference (same as `copyhub commands`):
+
+```bash
+copyhub config --client-id "<ID>" --client-secret "<SECRET>" [--redirect-port 19999] [--sheet-id "<SPREADSHEET_ID>"]
+copyhub login
+copyhub logout
+copyhub status
+copyhub start [--no-sheet] [--no-overlay] [--foreground]
+copyhub list    # alias: copyhub ls
+copyhub stop
+copyhub overlay
+copyhub commands    # alias: copyhub cmds
+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: 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. |
+| `copyhub start --foreground` | Same as above but attached to the terminal; **Ctrl+C** stops everything. |
+| `copyhub start --no-sheet` | Local history only; no Google Sheets writes. |
+| `copyhub start --no-overlay` | No Electron window; use env `COPYHUB_START_NO_OVERLAY=1` for the same effect. |
+| `copyhub list` / `copyhub ls` | Shows PID and start time if the daemon from `copyhub start` is running. |
+| `copyhub stop` | Stops the background daemon and its overlay child process. |
+| `copyhub overlay` | Runs **only** the Electron overlay (no clipboard daemon). Useful if you run the daemon separately or for debugging. |
+
+## Data locations
+
+Everything lives under **`~/.copyhub/`** (or `%USERPROFILE%\.copyhub` on Windows):
+
+| File | Contents |
+|------|----------|
+| `config.json` | OAuth credentials (if not only in `.env`), `googleSheetId`, `overlayAccelerator`, `overlayPlatform` |
+| `tokens.json` | OAuth refresh/access tokens |
+| `history.jsonl` | Local clipboard history (JSON Lines) |
+| `run.json` | Daemon PID and metadata (when using `copyhub start` without `--foreground`) |
+
+## Google Sheets layout
+
+- Rows are appended when Sheet sync is enabled and you are logged in.
+- New tabs are created per **local calendar day**, named: **`COPYHUB-YYYY-MM-DD`**.
+
+## Overlay (Electron)
+
+- Global shortcut defaults to **`CommandOrControl+Shift+H`** if nothing else is set (`Ctrl+Shift+H` on Windows/Linux, `⌘⇧H` on macOS-style wording in Electron).
+- **macOS**: you may need to grant **Accessibility** permissions for global shortcuts.
+- Some **`Control+Alt+…`** combinations do not register reliably on Windows; prefer alternatives suggested on the setup page.
+
+## License
+
+MIT — see `package.json`.

package/package.json

@@ -1,39 +1,39 @@
-{
-  "name": "copyhub-cli",
-  "version": "1.0.0",
-  "description": "CopyHub — clipboard, local history, Google Sheets sync (OAuth). Windows, macOS, Linux.",
-  "type": "module",
-  "bin": {
-    "copyhub": "./src/cli.js"
-  },
-  "scripts": {
-    "start": "node src/cli.js start",
-    "login": "node src/cli.js login",
-    "overlay": "node src/cli.js overlay"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "clipboard",
-    "google-sheets",
-    "oauth",
-    "sync",
-    "cli",
-    "cross-platform",
-    "windows",
-    "linux",
-    "macos"
-  ],
-  "files": ["src", "ui", ".env.example"],
-  "license": "MIT",
-  "dependencies": {
-    "clipboardy": "^4.0.0",
-    "dotenv": "^16.4.5",
-    "electron": "^33.2.0",
-    "commander": "^12.1.0",
-    "google-auth-library": "^9.15.0",
-    "googleapis": "^144.0.0",
-    "open": "^10.1.0"
-  }
-}
+{
+  "name": "copyhub-cli",
+  "version": "1.0.3",
+  "description": "CopyHub — clipboard, local history, Google Sheets sync (OAuth). Windows, macOS, Linux.",
+  "type": "module",
+  "bin": {
+    "copyhub": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js start",
+    "login": "node src/cli.js login",
+    "overlay": "node src/cli.js overlay"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "clipboard",
+    "google-sheets",
+    "oauth",
+    "sync",
+    "cli",
+    "cross-platform",
+    "windows",
+    "linux",
+    "macos"
+  ],
+  "files": ["src", "ui", ".env.example"],
+  "license": "MIT",
+  "dependencies": {
+    "clipboardy": "^4.0.0",
+    "dotenv": "^16.4.5",
+    "electron": "^33.2.0",
+    "commander": "^12.1.0",
+    "google-auth-library": "^9.15.0",
+    "googleapis": "^144.0.0",
+    "open": "^10.1.0"
+  }
+}