readshell 0.1.0 → 0.2.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 (4) hide show
  1. package/README.md +73 -64
  2. package/dist/index.js +299 -53
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,128 +1,137 @@
1
+ [English](README.md) | [中文](README_zh.md)
2
+
1
3
  # ReadShell
2
4
 
3
- > 终端内低打断轻阅读工具 · CLI Light Reading Tool for Developers
5
+ > CLI Light Reading Tool for Developers
4
6
 
5
7
  [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
6
8
  [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
7
9
 
8
10
  ---
9
11
 
10
- ## 🎯 解决什么问题
12
+ ## 🎯 Why ReadShell?
11
13
 
12
- ReadShell 解决的不是「没有地方看书」，而是：
14
+ ReadShell is not designed for "when you have no screens to read on", but rather:
13
15
 
14
- **开发间隙，你缺少一个不会把自己拖离工作流的短时休息入口。**
16
+ **During coding breaks, you need a quick reading escape that won't drag you out of your workflow.**
15
17
 
16
- | 现有替代方案 | 问题 |
18
+ | Alternatives | The Problem |
17
19
  |---|---|
18
- | 刷手机 | 打开就停不下来，10 分钟变 40 分钟 |
19
- | 刷网页 | 信息流劫持注意力，回不到工作状态 |
20
- | 微信读书 / Kindle | 需要切换设备或窗口，打断工作流 |
21
- | **ReadShell** | **原地休息，原地恢复，不离开终端** |
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.** |
24
+
25
+ ## 📈 Current MVP Progress (v0.1.0)
22
26
 
23
- ## 📈 当前阶段进度 (v0.1.0 MVP 达成)
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.
24
34
 
25
- 目前项目已完全兑现最初的《产品手册》设计目标（阶段一至阶段三皆已闭环上线）：
26
- - **核心阅读全格式支持**：原生支持 `.txt` 纯文本与 `.epub` 电子书解析。支持智能分页渲染、对话高亮以及平滑滚动。
27
- - **沉浸与反侦查系统**：独创的 `Boss Key` (老板键 `b`/`Esc`)，一键秒速伪装成标准的终端报错日志，深藏功与名。
28
- - **本地极速书房**：基于 SQLite 构建的零依赖本地数据中心。能够精准记忆任何一本书的字节读取偏移量，并在你退出时默默保存进度。
29
- - **深度时间流体验**：新增随时截取金句的快捷书签（`m` 键）以及基于你的本地 Buffer 实时演算的类 Kindle 阅读剩余时间预估。
35
+ ## 💡 The Philosophy (Developer's Monologue)
30
36
 
31
- ## 💡 为什么是这样？(内心独白)
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.
32
39
 
33
- ### 产品的本心：为什么要在终端里做阅读器？
34
- 作为一个开发者，IDE 和 Terminal 是我们日常最常驻的舒适区。当我们在编译等待、等待流水线构建或者单纯思维枯竭的 5 到 10 分钟里，常常需要一个能够**迅速切入又迅速抽离**的“精神避难所”。
35
- 刷网页容易被算法劫持，看手机更是会彻底打断心流进程。而终端——这个只有黑底白字、极度纯粹的环境，天生就带有一种克制的隔离感。
36
- **ReadShell** 试图在这个极度克制的环境里，以最低的启动摩擦力给你提供一处可以随时下潜和浮出的文字世界。它不需要全屏的臃肿软件，不需要花哨的 UI，在你同事的眼里，它就像一个正在执行的本地构建任务，静默而高效。
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.
37
41
 
38
- ### 技术选型的浪漫
39
- 在技术栈的设计上，为了追求极致的启动响应和最低的资源开销，我们抛弃了臃肿的 Electron 和图形界面：
40
- - **`Ink` 驱动的 TUI 美学**：用现代化的 React 响应式思维去描绘古老而极客的命令行界面。Flexbox 布局与 Hooks 状态机让控制台程序也能拥有细腻顺滑的反馈边界。
41
- - **本地绝对主权 (`SQLite`)**：拒绝云端绑架与冗余的网络请求。你所有的阅读记忆、章节骨架和金句书签，都以毫秒级的查询效率安静地存在于你硬盘上的只读账本里。它是彻底私密、极速的数据中枢。
42
- - **化繁为简的解析哲学**：无论是动辄几十兆的粗糙 TXT，还是内嵌错综复杂 HTML 的精品 EPUB 包，在经过流式切割和文本清洗后，最终都会化为终端里规整的行与列，在每个敲击的顺手瞬间抵达你的屏前。
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.
43
43
 
44
- ## ⚡ 快速开始
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.
45
49
 
46
- ### 安装
50
+ ## ⚡ Quick Start
51
+
52
+ ### Installation
47
53
 
48
54
  ```bash
49
55
  npm install -g readshell
50
56
  ```
51
57
 
52
- ### 基本使用
58
+ ### Basic Usage
53
59
 
54
60
  ```bash
55
- # 导入一本书 (支持 .txt 和 .epub)
56
- novel import ~/books/my-novel.epub
61
+ # Set Language (en / zh)
62
+ novel lang en
63
+
64
+ # Import a single book or batch import a folder (.txt and .epub)
65
+ novel import ~/books/
57
66
 
58
- # 恢复上次阅读（零摩擦入口）
67
+ # Resume last read (Zero-friction entry)
59
68
  novel resume
60
69
 
61
- # 打开指定书籍
70
+ # Open a specific book
62
71
  novel open <book-id>
63
72
 
64
- # 查看书架
73
+ # View library
65
74
  novel library
66
75
 
67
- # 移除书籍与记录
76
+ # Remove a book and its records
68
77
  novel remove <book-id>
69
78
  ```
70
79
 
71
- ### 阅读器快捷键
80
+ ### Reader Shortcuts
72
81
 
73
- | 快捷键 | 功能 |
82
+ | Key | Action |
74
83
  |---|---|
75
- | `空格` / `j` / `↓` | 下一页 |
76
- | `k` / `↑` | 上一页 |
77
- | `c` | 章节列表及书签列表 |
78
- | `Tab` | 章节弹出层中切换【目录/书签】 |
79
- | `m` / `M` | 将当前页首行标记为书签 |
80
- | `b` / `Esc` | Boss Key (老板键)，秒速伪装终端报错并自动存档 |
81
- | `q` | 正常退出并保存进度 |
82
- | `?` | 帮助 |
84
+ | `Space` / `j` / `↓` | Next Page |
85
+ | `k` / `↑` | Previous Page |
86
+ | `c` | Open Chapters and Bookmarks list |
87
+ | `Tab` | Switch between Chapters/Bookmarks in menu |
88
+ | `m` / `M` | Add Bookmark at the current page |
89
+ | `b` / `Esc` | Boss Key (disguise terminal as error and save) |
90
+ | `q` | Quit and save progress |
91
+ | `?` | Help |
83
92
 
84
- ## 🏗️ 技术栈
93
+ ## 🏗️ Tech Stack
85
94
 
86
95
  - **TypeScript** + **Node.js** (≥ 18)
87
- - **Ink** — React 范式的终端 UI 框架
88
- - **SQLite** (`better-sqlite3`) — 零依赖本地数据库
89
- - **Vitest** — 测试框架
96
+ - **Ink** — React-based Terminal UI framework
97
+ - **SQLite** (`better-sqlite3`) — Zero-dependency local DB
98
+ - **Vitest** — Testing Framework
90
99
 
91
- ## 📁 项目结构
100
+ ## 📁 Project Structure
92
101
 
93
102
  ```
94
103
  src/
95
- ├── cli/ # 命令层：解析参数，调用 service
96
- ├── ui/ # TUI 层（Ink 组件）
97
- ├── services/ # 业务逻辑层
98
- ├── parsers/ # 文件解析层（txt/epub）
99
- ├── db/ # 数据库层（SQLite）
100
- ├── config/ # 配置管理
101
- └── utils/ # 工具函数
104
+ ├── cli/ # CLI layer: args parsing, command dispatch
105
+ ├── ui/ # TUI layer (Ink components)
106
+ ├── services/ # Business logic
107
+ ├── parsers/ # Format parsers (txt/epub)
108
+ ├── db/ # Database layer (SQLite)
109
+ ├── config/ # Configuration management
110
+ └── utils/ # Utilities
102
111
  ```
103
112
 
104
- ## 🛠️ 开发
113
+ ## 🛠️ Development
105
114
 
106
115
  ```bash
107
- # 安装依赖
116
+ # Install dependencies
108
117
  npm install
109
118
 
110
- # 开发模式
119
+ # Dev mode
111
120
  npm run dev
112
121
 
113
- # 运行测试
122
+ # Run tests
114
123
  npm test
115
124
 
116
- # 构建
125
+ # Build
117
126
  npm run build
118
127
 
119
- # 代码检查
128
+ # Lint
120
129
  npm run lint
121
130
 
122
- # 格式化
131
+ # Format
123
132
  npm run format
124
133
  ```
125
134
 
126
- ## 📝 许可证
135
+ ## 📝 License
127
136
 
128
137
  [AGPL-3.0](LICENSE)