nber-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{nber_cli-0.2.0 → nber_cli-0.3.0}/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-06-03
+
+### Added
+- `feed init` subcommand: initialize a local SQLite feed cache and write its path to user config.
+- `feed fetch` subcommand: fetch NBER's new working papers RSS feed, cache seen items, and show newly discovered papers by default.
+- `feed fetch --max-items`: limit displayed feed output. When used without `--display-all`, display-all behavior is enabled automatically.
+- `feed migrate` subcommand: move the feed cache database and SQLite sidecar files to a new path, then update user config.
+- `feed clean` subcommand: clean cached feed database records by age, date range, or all records after interactive confirmation.
+- Python API exports for feed cache helpers and feed result models.
+
+### Changed
+- Added user config support at `~/.nber-cli/config.json` for the feed cache database path.
+- Expanded English and Chinese documentation for feed commands, configuration, Python API, and release notes.
+
 ## [0.2.0] - 2026-05-31
 
 ### Added

{nber_cli-0.2.0 → nber_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nber-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
 Project-URL: Homepage, https://github.com/sepinetam/nber-cli
 Project-URL: Repository, https://github.com/sepinetam/nber-cli

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/en/changelog.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented here.
 
+## 0.3.0 - 2026-06-03
+
+### Added
+
+- Added `nber-cli feed init` for creating a local SQLite feed cache.
+- Added `nber-cli feed fetch` for fetching NBER's new working papers RSS feed and showing newly cached items.
+- Added `nber-cli feed fetch --max-items` for limiting displayed feed output.
+- Added `nber-cli feed migrate` for moving the feed cache database and updating user config.
+- Added `nber-cli feed clean` for cleaning cached feed database records with confirmation.
+- Added Python API documentation for feed cache helpers and feed data models.
+
+### Changed
+
+- Added user config documentation for `~/.nber-cli/config.json` and `feed.db-path`.
+- Expanded English and Chinese feed cache documentation across CLI, getting started, configuration, and Python API pages.
+
 ## 0.2.0 - 2026-05-27
 
 ### Changed

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/en/cli.md

@@ -22,6 +22,7 @@ Running `nber-cli` without a subcommand prints the top-level help and exits succ
 | `download` | Download one or more paper PDFs. |
 | `info` | Show metadata and abstract for one paper. |
 | `search` | Search NBER working papers. |
+| `feed` | Manage the NBER new working papers RSS feed cache. |
 | `mcp-server` | Start the MCP server for agents. |
 
 ## download
@@ -139,6 +140,111 @@ nber-cli search "inflation" -f json
 
 When only `--start-date` is provided, NBER-CLI automatically uses the current date as the end date.
 
+## feed
+
+`feed` works with NBER's new working papers RSS feed and a local SQLite cache. The cache tracks which RSS items have already been seen, so `feed fetch` can show only newly discovered papers by default.
+
+### feed init
+
+Initialize the feed cache database and write the database path to the user config:
+
+```bash
+nber-cli feed init
+nber-cli feed init --db-path ~/.nber-cli/feed.db
+```
+
+If `--db-path` is omitted, the default database path is `~/.nber-cli/feed.db`.
+
+### feed fetch
+
+Fetch the RSS feed, store all fetched items in the cache, and display only new items by default:
+
+```bash
+nber-cli feed fetch
+```
+
+Display all fetched RSS items, including items already present in the cache:
+
+```bash
+nber-cli feed fetch --display-all true
+nber-cli feed fetch --display-all
+```
+
+Limit displayed output:
+
+```bash
+nber-cli feed fetch --max-items 5
+```
+
+When `--max-items` is provided and `--display-all` is omitted, `--display-all` defaults to `true`. This makes `nber-cli feed fetch --max-items 5` show the first five fetched RSS items instead of showing nothing when there are no new items.
+
+Return JSON:
+
+```bash
+nber-cli feed fetch --format json
+nber-cli feed fetch -f json
+```
+
+### feed migrate
+
+Move the feed cache database to a new path and update the user config:
+
+```bash
+nber-cli feed migrate ~/data/nber-feed.db
+```
+
+Migration moves the SQLite database file and any SQLite sidecar files such as `-wal`, `-shm`, and `-journal`. The target path must not already exist.
+
+### feed clean
+
+Clean cached feed database records. This deletes records from the local cache, not from NBER. Deleted cache records may be fetched again as new items if they still appear in the RSS feed.
+
+Clean records not seen for 30 days:
+
+```bash
+nber-cli feed clean
+nber-cli feed clean --days 30
+```
+
+Clean all cached records:
+
+```bash
+nber-cli feed clean --all
+```
+
+Clean records by last-seen date:
+
+```bash
+nber-cli feed clean --end-date 2026-05-31
+nber-cli feed clean --start-date 2026-05-01 --end-date 2026-05-31
+```
+
+`--end-date` without `--start-date` cleans from the earliest cached record through the end date. `--start-date` and `--end-date` are inclusive. Passing only `--start-date` is invalid.
+
+Before deleting anything, `feed clean` prints how many cached records match and asks for confirmation:
+
+```text
+This operation is irreversible.
+Deleted cache records may be fetched again as new items if they still appear in the RSS feed.
+Continue? [y/N]:
+```
+
+Only `y` or `Y` continues. Any other response aborts without deleting records.
+
+### feed Options
+
+| Subcommand | Option | Description |
+| --- | --- | --- |
+| `init` | `--db-path` | SQLite cache database path. Defaults to `~/.nber-cli/feed.db`. |
+| `fetch` | `--display-all [true|false]` | Display all fetched RSS items instead of only new items. |
+| `fetch` | `--format`, `-f` | Output format: `list` or `json`. Defaults to `list`. |
+| `fetch` | `--max-items` | Maximum number of feed items to display. |
+| `migrate` | `new_db_path` | New SQLite cache database path. |
+| `clean` | `--days` | Clean cached records not seen for this many days. Defaults to `30`. |
+| `clean` | `--all` | Clean all cached feed records. |
+| `clean` | `--start-date` | Clean cached records last seen on or after this date, formatted `YYYY-MM-DD`. |
+| `clean` | `--end-date` | Clean cached records last seen on or before this date, formatted `YYYY-MM-DD`. |
+
 ## mcp-server
 
 Start the default stdio MCP server:
@@ -172,4 +278,4 @@ For client configuration and tool details, see [MCP Server](mcp.md).
 
 ## Output Formats
 
-`info` and `search` default to `list`, a readable text format. Use `--format json` when piping output into scripts or agent workflows.
+`info`, `search`, and `feed fetch` default to `list`, a readable text format. Use `--format json` when piping output into scripts or agent workflows.

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/en/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-NBER-CLI currently uses built-in runtime defaults rather than a user configuration file. The defaults are intentionally conservative and work for both CLI and MCP usage.
+Most NBER-CLI runtime behavior uses built-in defaults. The feed cache also uses a small user config file to remember the SQLite database path selected by `nber-cli feed init` or `nber-cli feed migrate`.
 
 ## Runtime Defaults
 
@@ -15,6 +15,54 @@ NBER-CLI currently uses built-in runtime defaults rather than a user configurati
 
 These values live in `NBERCLIConfig` and `NBER_CLI_CONFIG`.
 
+## User Config File
+
+The user config file is:
+
+```text
+~/.nber-cli/config.json
+```
+
+At the moment, the config file is used for feed cache settings:
+
+```json
+{
+  "feed": {
+    "db-path": "/Users/name/.nber-cli/feed.db"
+  }
+}
+```
+
+`feed.db-path` points to the SQLite database used by `nber-cli feed fetch` and `nber-cli feed clean`.
+
+## Feed Cache Database
+
+Default feed cache database path:
+
+```text
+~/.nber-cli/feed.db
+```
+
+Initialize the default cache:
+
+```bash
+nber-cli feed init
+```
+
+Initialize a cache at a custom path:
+
+```bash
+nber-cli feed init --db-path ~/data/nber-feed.db
+```
+
+Move an existing cache and update the config:
+
+```bash
+nber-cli feed migrate ~/data/nber-feed.db
+```
+
+The feed cache stores RSS items that have already been seen. `feed fetch` uses this cache to decide which items are new. `feed clean` deletes records from this local cache; if deleted records still appear in the RSS feed, they may be fetched again as new items.
+
 ## Output Paths
 
 Single download default:

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/en/getting-started.md

@@ -73,6 +73,36 @@ Use `--all` to include related fields and published-version information when NBE
 nber-cli info w25000 --all
 ```
 
+## Follow New Papers with the Feed Cache
+
+Initialize the local RSS feed cache:
+
+```bash
+nber-cli feed init
+```
+
+Fetch the NBER new working papers RSS feed:
+
+```bash
+nber-cli feed fetch
+```
+
+The first fetch stores the current RSS items in the cache and displays them as new. Later fetches show only items that were not already cached.
+
+Limit output while showing the latest fetched items:
+
+```bash
+nber-cli feed fetch --max-items 5
+```
+
+Clean old cache records:
+
+```bash
+nber-cli feed clean --days 30
+```
+
+`feed clean` asks for confirmation before deleting cached records.
+
 ## Download a PDF
 
 Download into the current directory:

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/en/index.md

@@ -8,6 +8,7 @@ NBER-CLI focuses on the common research loop around NBER working papers:
 
 - Search for papers by keyword, author, title, abstract, or paper number.
 - Inspect a paper's title, authors, date, abstract, URL, and related metadata.
+- Follow new working papers through NBER's RSS feed and a local cache.
 - Download a PDF by paper ID.
 - Run batch downloads into a target directory.
 - Serve paper search, lookup, and download operations as MCP tools.
@@ -19,6 +20,7 @@ Run without installing:
 ```bash
 uvx nber-cli search "Labor Economic"
 uvx nber-cli info w25000
+uvx nber-cli feed fetch --max-items 5
 uvx nber-cli download w34567
 ```
 
@@ -28,6 +30,7 @@ Install as a reusable command:
 uv tool install nber-cli
 nber-cli search "Labor Economic"
 nber-cli info w25000
+nber-cli feed fetch --max-items 5
 nber-cli download w34567
 ```
 
@@ -66,4 +69,4 @@ Add it to an MCP client:
 
 ## Project Status
 
-The current public command model is `nber-cli` v0.2.0. The CLI is intentionally small and script-friendly: text output is optimized for human reading, and `--format json` is available where structured output matters.
+The current public command model is `nber-cli` v0.3.0. The CLI is intentionally small and script-friendly: text output is optimized for human reading, and `--format json` is available where structured output matters.

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/en/python-api.md

@@ -2,6 +2,8 @@
 
 NBER-CLI exposes the same core functionality as importable Python functions. The API is asynchronous because lookup, search, and downloads perform network I/O.
 
+Feed cache helpers are synchronous because they perform local SQLite work and a synchronous RSS fetch.
+
 ## Install
 
 ```bash
@@ -90,6 +92,61 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Work with the Feed Cache
+
+Initialize the default feed cache:
+
+```python
+from nber_cli import init_feed_database
+
+db_path = init_feed_database()
+print(db_path)
+```
+
+Fetch the NBER RSS feed and display new cached items:
+
+```python
+from nber_cli import feed_results, fetch_feed
+
+result = fetch_feed()
+payload = feed_results(result)
+print(payload["new_count"])
+for item in payload["results"]:
+    print(item["id"], item["title"])
+```
+
+Display all fetched RSS items and limit the returned items:
+
+```python
+from nber_cli import fetch_feed
+
+result = fetch_feed(display_all=True, max_items=5)
+```
+
+Move the feed cache database:
+
+```python
+from pathlib import Path
+
+from nber_cli import migrate_feed_database
+
+old_path, new_path = migrate_feed_database(Path("~/data/nber-feed.db"))
+```
+
+Clean cached feed database records:
+
+```python
+from nber_cli import clean_feed_cache
+
+preview = clean_feed_cache(days=30, dry_run=True)
+print(preview.matched_count)
+
+result = clean_feed_cache(days=30)
+print(result.deleted_count)
+```
+
+`clean_feed_cache` deletes local cache records only. If deleted records still appear in the RSS feed, a later `fetch_feed` call may return them as new items again.
+
 ## Data Models
 
 ### NBER
@@ -118,6 +175,43 @@ asyncio.run(main())
 | `start_date` | `str` or `None` | Applied start date. |
 | `end_date` | `str` or `None` | Applied end date. |
 
+### NBERFeedItem
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `paper_id` | `str` | Paper ID, for example `w35254`. |
+| `title` | `str` | Paper title parsed from the RSS item. |
+| `authors` | `list[str]` | Author names parsed from the RSS title. |
+| `abstract` | `str` | RSS item description. |
+| `url` | `str` | Canonical NBER paper URL without the RSS fragment. |
+| `source_url` | `str` | Original RSS item URL. |
+| `guid` | `str` | RSS item GUID. |
+
+### NBERFeedFetchResult
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `source_url` | `str` | RSS feed URL. |
+| `database_path` | `Path` | SQLite cache database path. |
+| `total_fetched` | `int` | Number of RSS items fetched. |
+| `new_count` | `int` | Number of fetched items that were not already in the cache. |
+| `display_all` | `bool` | Whether returned items include all fetched items. |
+| `items` | `list[NBERFeedItem]` | Items selected for display or structured output. |
+| `max_items` | `int` or `None` | Display limit when provided. |
+
+### NBERFeedCleanResult
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `database_path` | `Path` | SQLite cache database path. |
+| `matched_count` | `int` | Number of cache records matching the clean criteria. |
+| `deleted_count` | `int` | Number of cache records deleted. |
+| `mode` | `str` | Clean mode: `days`, `all`, or `date-range`. |
+| `days` | `int` or `None` | Day threshold for `days` mode. |
+| `start_date` | `str` or `None` | Inclusive start date for `date-range` mode. |
+| `end_date` | `str` or `None` | Inclusive end date for `date-range` mode. |
+| `dry_run` | `bool` | Whether the operation only counted matching records. |
+
 ### DownloadFailure
 
 | Field | Type | Description |
@@ -137,12 +231,13 @@ asyncio.run(main())
 Use formatter helpers when you want stable dictionaries for JSON output or MCP-style responses:
 
 ```python
-from nber_cli import info, related, search_results
+from nber_cli import feed_results, info, related, search_results
 ```
 
 - `info(paper)` returns core metadata.
 - `related(paper)` returns related optional fields.
 - `search_results(results)` returns a structured search payload.
+- `feed_results(result)` returns a structured feed fetch payload.
 
 For human-readable text output, use the text formatters:
 

nber_cli-0.3.0/docs/zh/changelog.md

@@ -0,0 +1,41 @@
+# 更新日志
+
+这里记录项目的重要变更。
+
+## 0.3.0 - 2026-06-03
+
+### Added
+
+- 添加 `nber-cli feed init`，用于创建本地 SQLite feed 缓存。
+- 添加 `nber-cli feed fetch`，用于获取 NBER 最新工作论文 RSS feed 并显示新缓存的条目。
+- 添加 `nber-cli feed fetch --max-items`，用于限制 feed 输出数量。
+- 添加 `nber-cli feed migrate`，用于移动 feed 缓存数据库并更新用户配置。
+- 添加 `nber-cli feed clean`，用于在确认后清理 feed 缓存数据库记录。
+- 补充 feed 缓存辅助函数和 feed 数据模型的 Python API 文档。
+
+### Changed
+
+- 添加 `~/.nber-cli/config.json` 和 `feed.db-path` 的用户配置文档。
+- 扩展中英文 CLI、快速开始、配置和 Python API 页面中的 feed 缓存文档。
+
+## 0.2.0 - 2026-05-27
+
+### Changed
+
+- 将 CLI 重构为 `nber-cli download ...` 子命令语法。
+- 添加 `--file/-f` 和 `--save-base/-s` 路径处理行为。
+- 添加 `--batch/-b` 多编号下载模式。
+- 移除基于数据库的下载状态跟踪。
+- 将下载器简化为直接异步 HTTP PDF 获取。
+- 更新 v0.2 命令模型文档。
+- 移除旧 web UI 模块和脚本入口。
+
+## 0.1.4 - 2025-08-09
+
+### Added
+
+- 添加 `--version` / `-v` 参数用于显示当前版本。
+- 添加更完整的帮助信息和示例。
+- 添加 `__main__.py` 以支持 `python -m nber_cli`。
+- 添加参数分组以改善 CLI 结构。
+- 不带参数运行时自动显示帮助信息。

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/zh/cli.md

@@ -22,6 +22,7 @@ nber-cli [--version] <command> [options]
 | `download` | 下载一篇或多篇论文 PDF。 |
 | `info` | 显示单篇论文的元数据和摘要。 |
 | `search` | 搜索 NBER 工作论文。 |
+| `feed` | 管理 NBER 最新工作论文 RSS feed 的本地缓存。 |
 | `mcp-server` | 启动给 Agent 使用的 MCP server。 |
 
 ## download
@@ -139,6 +140,111 @@ nber-cli search "inflation" -f json
 
 只提供 `--start-date` 时，NBER-CLI 会自动使用当前日期作为结束日期。
 
+## feed
+
+`feed` 用于处理 NBER 最新工作论文 RSS feed 和本地 SQLite 缓存。缓存会记录哪些 RSS 条目已经见过，因此 `feed fetch` 默认只显示新发现的论文。
+
+### feed init
+
+初始化 feed 缓存数据库，并把数据库路径写入用户配置：
+
+```bash
+nber-cli feed init
+nber-cli feed init --db-path ~/.nber-cli/feed.db
+```
+
+如果省略 `--db-path`，默认数据库路径是 `~/.nber-cli/feed.db`。
+
+### feed fetch
+
+获取 RSS feed，把所有获取到的条目写入缓存，并默认只显示新的条目：
+
+```bash
+nber-cli feed fetch
+```
+
+显示所有获取到的 RSS 条目，包括缓存中已经存在的条目：
+
+```bash
+nber-cli feed fetch --display-all true
+nber-cli feed fetch --display-all
+```
+
+限制输出数量：
+
+```bash
+nber-cli feed fetch --max-items 5
+```
+
+当提供 `--max-items` 且没有提供 `--display-all` 时，`--display-all` 默认会变成 `true`。因此 `nber-cli feed fetch --max-items 5` 会显示本次获取到的前 5 个 RSS 条目，而不是在没有新条目时显示空结果。
+
+返回 JSON：
+
+```bash
+nber-cli feed fetch --format json
+nber-cli feed fetch -f json
+```
+
+### feed migrate
+
+移动 feed 缓存数据库到新路径，并更新用户配置：
+
+```bash
+nber-cli feed migrate ~/data/nber-feed.db
+```
+
+迁移会移动 SQLite 数据库文件，以及 `-wal`、`-shm`、`-journal` 等 SQLite sidecar 文件。目标路径不能已经存在。
+
+### feed clean
+
+清理 feed 缓存数据库记录。这个操作删除的是本地缓存记录，不会影响 NBER。被删除的缓存记录如果仍然出现在 RSS feed 中，后续可能会再次作为新条目被获取。
+
+清理 30 天没有再次出现的记录：
+
+```bash
+nber-cli feed clean
+nber-cli feed clean --days 30
+```
+
+清理全部缓存记录：
+
+```bash
+nber-cli feed clean --all
+```
+
+按 last-seen 日期清理记录：
+
+```bash
+nber-cli feed clean --end-date 2026-05-31
+nber-cli feed clean --start-date 2026-05-01 --end-date 2026-05-31
+```
+
+只提供 `--end-date` 时，会从最早的缓存记录清理到该结束日期。`--start-date` 和 `--end-date` 都是前后包含的。只提供 `--start-date` 是无效的。
+
+删除前，`feed clean` 会先打印匹配到的缓存记录数量，并要求确认：
+
+```text
+This operation is irreversible.
+Deleted cache records may be fetched again as new items if they still appear in the RSS feed.
+Continue? [y/N]:
+```
+
+只有输入 `y` 或 `Y` 才会继续。其他输入都会中止，不删除记录。
+
+### feed 选项
+
+| 子命令 | 选项 | 说明 |
+| --- | --- | --- |
+| `init` | `--db-path` | SQLite 缓存数据库路径，默认是 `~/.nber-cli/feed.db`。 |
+| `fetch` | `--display-all [true|false]` | 显示所有获取到的 RSS 条目，而不是只显示新条目。 |
+| `fetch` | `--format`, `-f` | 输出格式：`list` 或 `json`，默认是 `list`。 |
+| `fetch` | `--max-items` | 最多显示多少个 feed 条目。 |
+| `migrate` | `new_db_path` | 新的 SQLite 缓存数据库路径。 |
+| `clean` | `--days` | 清理这么多天没有再次出现的缓存记录，默认是 `30`。 |
+| `clean` | `--all` | 清理全部 feed 缓存记录。 |
+| `clean` | `--start-date` | 清理 last-seen 日期在该日期及之后的缓存记录，格式为 `YYYY-MM-DD`。 |
+| `clean` | `--end-date` | 清理 last-seen 日期在该日期及之前的缓存记录，格式为 `YYYY-MM-DD`。 |
+
 ## mcp-server
 
 启动默认 stdio MCP server：
@@ -172,4 +278,4 @@ nber-cli mcp-server --transport streamable_http --port 8000
 
 ## 输出格式
 
-`info` 和 `search` 默认使用 `list`，这是一种适合人阅读的文本格式。需要把输出交给脚本或 Agent 工作流时，请使用 `--format json`。
+`info`、`search` 和 `feed fetch` 默认使用 `list`，这是一种适合人阅读的文本格式。需要把输出交给脚本或 Agent 工作流时，请使用 `--format json`。

{nber_cli-0.2.0 → nber_cli-0.3.0}/docs/zh/configuration.md

@@ -1,6 +1,6 @@
 # 配置
 
-NBER-CLI 当前使用内置运行时默认值，而不是用户配置文件。这些默认值刻意保持保守，适合 CLI 和 MCP 两种用法。
+NBER-CLI 的大多数运行时行为使用内置默认值。feed 缓存还会使用一个小型用户配置文件，用来记住 `nber-cli feed init` 或 `nber-cli feed migrate` 选择的 SQLite 数据库路径。
 
 ## 运行时默认值
 
@@ -15,6 +15,54 @@ NBER-CLI 当前使用内置运行时默认值，而不是用户配置文件。
 
 这些值位于 `NBERCLIConfig` 和 `NBER_CLI_CONFIG`。
 
+## 用户配置文件
+
+用户配置文件路径是：
+
+```text
+~/.nber-cli/config.json
+```
+
+目前配置文件用于 feed 缓存设置：
+
+```json
+{
+  "feed": {
+    "db-path": "/Users/name/.nber-cli/feed.db"
+  }
+}
+```
+
+`feed.db-path` 指向 `nber-cli feed fetch` 和 `nber-cli feed clean` 使用的 SQLite 数据库。
+
+## Feed 缓存数据库
+
+默认 feed 缓存数据库路径：
+
+```text
+~/.nber-cli/feed.db
+```
+
+初始化默认缓存：
+
+```bash
+nber-cli feed init
+```
+
+初始化到自定义路径：
+
+```bash
+nber-cli feed init --db-path ~/data/nber-feed.db
+```
+
+移动已有缓存并更新配置：
+
+```bash
+nber-cli feed migrate ~/data/nber-feed.db
+```
+
+feed 缓存会存储已经见过的 RSS 条目。`feed fetch` 使用这个缓存判断哪些条目是新的。`feed clean` 删除的是本地缓存记录；如果被删除的记录仍然出现在 RSS feed 中，后续可能会再次作为新条目被获取。
+
 ## 输出路径
 
 单篇下载默认行为：