readshell 0.3.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +17 -13
  2. package/README.md +139 -90
  3. package/dist/index.js +1235 -216
  4. package/dist/index.js.map +1 -1
  5. package/package.json +10 -5
package/LICENSE CHANGED
@@ -1,17 +1,21 @@
1
- GNU AFFERO GENERAL PUBLIC LICENSE
2
- Version 3, 19 November 2007
1
+ MIT License
3
2
 
4
- Copyright (C) 2026 ReadShell
3
+ Copyright (c) 2026 ReadShell / davidy
5
4
 
6
- This program is free software: you can redistribute it and/or modify
7
- it under the terms of the GNU Affero General Public License as published by
8
- the Free Software Foundation, either version 3 of the License, or
9
- (at your option) any later version.
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
10
11
 
11
- This program is distributed in the hope that it will be useful,
12
- but WITHOUT ANY WARRANTY; without even the implied warranty of
13
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
- GNU Affero General Public License for more details.
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
15
14
 
16
- You should have received a copy of the GNU Affero General Public License
17
- along with this program. If not, see <https://www.gnu.org/licenses/>.
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,143 +1,192 @@
1
1
  [English](README.md) | [中文](README_zh.md)
2
2
 
3
+ <div align="center">
4
+
3
5
  # ReadShell
4
6
 
5
- > CLI Light Reading Tool for Developers
7
+ **Your terminal already has everything. Now it has a bookshelf.**
8
+
9
+ [![npm version](https://img.shields.io/npm/v/readshell.svg)](https://www.npmjs.com/package/readshell)
10
+ [![npm downloads](https://img.shields.io/npm/dm/readshell.svg)](https://www.npmjs.com/package/readshell)
11
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
12
+ [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org)
13
+
14
+ *A low-friction reading tool for developers who never leave the terminal. Free and open source — no accounts, no servers, no paid tier.*
15
+
16
+ ![ReadShell Demo](./docs/demo.gif)
6
17
 
7
- [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
8
- [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
18
+ </div>
9
19
 
10
20
  ---
11
21
 
12
- ## 🎯 Why ReadShell?
22
+ ## The Problem
13
23
 
14
- ReadShell is not designed for "when you have no screens to read on", but rather:
24
+ Waiting for a build to finish? Pipeline still running? You have 5 minutes.
15
25
 
16
- **During coding breaks, you need a quick reading escape that won't drag you out of your workflow.**
26
+ You open your phone. 40 minutes later, you're still scrolling.
17
27
 
18
- | Alternatives | The Problem |
19
- |---|---|
20
- | Scrolling Social Media | Hard to stop; 10 minutes turns into 40 minutes. |
21
- | Web Browsing | Information overload hijacked by algorithms; hard to get back to work. |
22
- | Desktop Apps / Kindle | Requires switching context, devices, or windows, breaking your flow. |
23
- | **ReadShell** | **Rest where you are, recover your flow, never leave the terminal.** |
28
+ ReadShell is built for that gap — a reading space that lives inside your workflow, not outside it.
29
+ ```bash
30
+ novel resume
31
+ ```
32
+
33
+ One command. Back to where you were. Back to work when you're ready.
34
+
35
+ ---
24
36
 
25
- ## 📈 Current MVP Progress (v0.1.0)
37
+ ## Features
26
38
 
27
- Our initial MVP goals are fully realized:
28
- - **Core Format Support**: Native parsing for `.txt` plain text and `.epub` ebooks. Features intelligent pagination, dialogue highlighting, and smooth scrolling.
29
- - **Immersion & Boss Key**: Original `Boss Key` (`b`/`Esc`) instantly disguises the reader as a standard terminal error log, saving your progress seamlessly.
30
- - **Local Lightning-Fast Library**: A zero-dependency local data center built entirely on SQLite. Accurately remembers byte-offsets and silently saves your progress upon exiting.
31
- - **Deep Flow Reading**: Features rapid bookmarks (`m` key) and localized Kindle-style "Time Left" estimations based on your reading speed.
32
- - **Batch Folder Import**: Recursively scan and import entire folders of books at once.
33
- - **I18n Support**: Native support for English and Chinese.
39
+ **📖 `novel resume` — Zero-friction re-entry**
40
+ The most important command. Picks up exactly where you left off, down to the byte.
34
41
 
35
- ## 💡 The Philosophy (Developer's Monologue)
42
+ **🥷 Boss Key (`b` / `Esc`) — Instant disguise**
43
+ One keypress transforms the reader into a convincing terminal error log (nodejs / python / java / c / go). Your secret is safe.
44
+ ![Boss Key Demo](./docs/error.png)
45
+ *Boss Key wipes the scrollback buffer and shows a fake error. `novel resume` jumps back to the exact spot.*
36
46
 
37
- ### Why build a reader in the terminal?
38
- As developers, the IDE and Terminal are our natural habitats. When we are waiting for a build, a pipeline to finish, or just experiencing a 5-10 minute mental block, we need a "spiritual refuge" that is easy to slip into and easy to drop out of.
47
+ **🔄 Folder sync — multi-device, no server**
48
+ Point ReadShell at any folder synced by iCloud Drive, Dropbox, OneDrive, 坚果云, or Syncthing. Progress, bookmarks (including deletions), and reading stats merge across devices automatically on open/exit. Nothing is ever uploaded to a ReadShell server — there isn't one.
39
49
 
40
- Web browsers easily hijack your attention, and phones completely shatter your flow state. But the terminal—a pure, text-only monochrome environment—naturally carries a restrained sense of isolation.
50
+ **📊 `novel stats` — GitHub-style heatmap**
51
+ A year of reading at a glance, plus reading days, total time, books read, and streaks — aggregated across all synced devices.
41
52
 
42
- **ReadShell** attempts to provide a text-based sanctuary with the lowest friction possible within this highly restrained environment. No bloated UI, no distractions. To your coworkers, it just looks like another local build task running silently and efficiently.
53
+ **🔖 Bookmarks (`m`) + free export**
54
+ Capture a passage mid-read, revisit via the chapter navigator (`c`), export everything with `novel bookmarks export --format md|json`.
43
55
 
44
- ### The Romance of Tech Choices
45
- To achieve ultimate speed and minimal resource overhead, we abandoned Electron and GUI frameworks:
46
- - **`Ink` TUI Aesthetics**: Drawing an old-school, geeky CLI using Modern React reactive principles. Flexbox and Hooks give CLI apps smooth boundary feedback.
47
- - **Absolute Local Sovereignty (`SQLite`)**: Rejecting cloud lock-in and redundant network requests. Your reading memories, chapter skeletons, and bookmarks exist cleanly in a lightning-fast read-only ledger on your SSD.
48
- - **Philosophy of Simplification**: Whether it’s a massive raw TXT or a complex HTML-embedded EPUB, they are streamed, parsed, and cleansed into structured terminal rows, arriving right before your eyes at the press of a key.
56
+ **📚 Batch import**
57
+ `novel import ~/books/` — recursively imports `.txt`, `.epub`, and `.md` files.
49
58
 
50
- ## ⚡ Quick Start
59
+ **🌐 i18n**
60
+ Native Chinese and English support (`novel lang zh|en`).
51
61
 
52
- ### Installation
62
+ ---
53
63
 
64
+ ## Quick Start
54
65
  ```bash
55
66
  npm install -g readshell
56
67
  ```
57
-
58
- ### Basic Usage
59
-
60
68
  ```bash
61
- # Set Language (en / zh)
62
- novel lang en
63
-
64
- # Import a single book or batch import a folder (.txt and .epub)
69
+ # Import your books
65
70
  novel import ~/books/
66
71
 
67
- # Resume last read (Zero-friction entry)
72
+ # Jump back in
68
73
  novel resume
69
74
 
70
- # Open a specific book
75
+ # Or pick a specific book
71
76
  novel open <book-id>
72
77
 
73
- # Configure application (language | line-spacing | reading-mode)
74
- novel config language en
75
- novel config line-spacing 1
76
- novel config reading-mode scroll
77
-
78
- # View book list
78
+ # Browse your library
79
79
  novel list
80
+ ```
81
+
82
+ ### Reader Controls
80
83
 
81
- # Remove a book and its records
82
- novel remove <book-id>
84
+ | Key | Action |
85
+ |---|---|
86
+ | `Space` / `j` / `↓` / `f` | Next page / scroll down |
87
+ | `k` / `↑` | Previous page / scroll up |
88
+ | `g` / `G` | First / last page |
89
+ | `c` | Chapter list & bookmarks |
90
+ | `Tab` | Toggle chapters / bookmarks |
91
+ | `m` | Add bookmark |
92
+ | `b` / `Esc` | **Boss Key** — disguise & save |
93
+ | `q` | Quit & save |
94
+ | `?` | Help |
83
95
 
84
- # Check and update to the latest version
85
- novel update
96
+ ### Commands
97
+ ```bash
98
+ novel import <path> # file or directory (txt / epub / md)
99
+ novel list # library
100
+ novel open <id|title> # open a book
101
+ novel resume # resume last position
102
+ novel remove <id|title> # remove from library
103
+ novel stats # reading heatmap & streaks
104
+ novel bookmarks export [--format json|md] [--out file]
105
+ novel sync --dir <path> [--with-books] # set sync folder & sync
106
+ novel sync # sync with saved folder
107
+ novel sync --off # disable sync
108
+ novel lang zh|en # interface language
109
+ novel config <key> <value> # language | line-spacing | reading-mode | boss-key-lang
110
+ novel update # update to latest
86
111
  ```
87
112
 
88
- ### Reader Shortcuts
113
+ ---
89
114
 
90
- | `Space` / `j` / `↓` | Next Page (or Scroll half-page in scroll mode) |
91
- | `k` / `↑` | Previous Page (or Scroll half-page in scroll mode) |
92
- | `c` | **Open Chapters and Bookmarks list (Quick Navigation)** |
93
- | `Tab` | Switch between Chapters/Bookmarks in menu |
94
- | `m` / `M` | Add Bookmark at the current page |
95
- | `b` / `Esc` | Boss Key (instantly disguise terminal and save) |
96
- | `q` | Quit and save progress |
97
- | `?` | Help |
115
+ ## Folder Sync
98
116
 
99
- ## 🏗️ Tech Stack
117
+ ReadShell syncs through a plain folder — no account, no server. Each device writes a snapshot to `<syncDir>/readshell-sync/devices/<deviceId>.json` and merges every other device's file (last-write-wins progress, bookmark tombstones, session union).
100
118
 
101
- - **TypeScript** + **Node.js** (≥ 18)
102
- - **Ink** — React-based Terminal UI framework
103
- - **SQLite** (`better-sqlite3`) — Zero-dependency local DB
104
- - **Vitest** — Testing Framework
119
+ Pick a folder that your sync tool already watches:
105
120
 
106
- ## 📁 Project Structure
121
+ ```bash
122
+ # iCloud Drive (macOS)
123
+ novel sync --dir "$HOME/Library/Mobile Documents/com~apple~CloudDocs/ReadShell"
107
124
 
125
+ # Dropbox
126
+ novel sync --dir ~/Dropbox/ReadShell
127
+
128
+ # 坚果云 / OneDrive / Syncthing — same idea, any synced folder
129
+ novel sync --dir ~/Nutstore/ReadShell
108
130
  ```
109
- src/
110
- ├── cli/ # CLI layer: args parsing, command dispatch
111
- ├── ui/ # TUI layer (Ink components)
112
- ├── services/ # Business logic
113
- ├── parsers/ # Format parsers (txt/epub)
114
- ├── db/ # Database layer (SQLite)
115
- ├── config/ # Configuration management
116
- └── utils/ # Utilities
117
- ```
118
131
 
119
- ## 🛠️ Development
132
+ Add `--with-books` to also copy book files into the sync folder — other devices will auto-import books they don't have yet. Without it, only progress/bookmarks/stats sync (books are matched by file hash).
133
+
134
+ Sync runs automatically when the reader opens (pull) and exits (push + pull), silently and bounded to ~2s. `novel sync --off` disables it.
135
+
136
+ ---
137
+
138
+ ## Migrating from readshell-pro
120
139
 
121
140
  ```bash
122
- # Install dependencies
123
- npm install
141
+ npm uninstall -g readshell-pro && npm install -g readshell
142
+ ```
143
+
144
+ Your library, progress, and bookmarks are preserved — the data directory is unchanged. Cloud auth keys are cleaned up automatically on first run.
145
+
146
+ ---
147
+
148
+ ## Why the terminal?
149
+
150
+ The terminal is already where you live. It's focused, text-only, and distraction-resistant by nature.
124
151
 
125
- # Dev mode
126
- npm run dev
152
+ ReadShell doesn't ask you to context-switch. It sits quietly in your workflow — invisible to colleagues, zero install friction, no accounts, no cloud, no noise.
127
153
 
128
- # Run tests
129
- npm test
154
+ Your reading history lives entirely on your local machine in a SQLite file (plus the sync folder you choose). Nothing leaves your disk otherwise.
130
155
 
131
- # Build
132
- npm run build
156
+ ---
157
+
158
+ ## Tech Stack
133
159
 
134
- # Lint
135
- npm run lint
160
+ - **TypeScript** + **Node.js** ≥ 20
161
+ - **Ink** — React-based TUI framework
162
+ - **SQLite** (`better-sqlite3`) — local-first, zero-dependency storage
163
+ - **Vitest** — testing
136
164
 
137
- # Format
138
- npm run format
165
+ ## Project Structure
166
+ ```
167
+ src/
168
+ ├── cli/ # Command layer
169
+ ├── ui/ # TUI components (Ink)
170
+ ├── services/ # Business logic (incl. folder sync, stats)
171
+ ├── parsers/ # txt / epub / md parsers
172
+ ├── db/ # SQLite layer
173
+ ├── config/ # Config management
174
+ └── utils/
139
175
  ```
140
176
 
141
- ## 📝 License
177
+ ---
178
+
179
+ ## Contributing
180
+
181
+ Issues, ideas, and PRs are welcome — see [CONTRIBUTING](docs/CONTRIBUTING.md).
182
+ If ReadShell fits into your workflow, a ⭐ helps more people find it.
183
+
184
+ ## Sponsor
185
+
186
+ If ReadShell saves you time, consider supporting development: https://readshell.com/sponsor
187
+
188
+ ---
189
+
190
+ ## License
142
191
 
143
- [AGPL-3.0](LICENSE)
192
+ [MIT](LICENSE)