nber-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{nber_cli-0.4.0 → nber_cli-0.5.0}/.claude-plugin/marketplace.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "nber-cli",
   "description": "Claude Code marketplace for NBER-CLI research workflows.",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "owner": {
     "name": "Song Tan",
     "email": "sepinetam@gmail.com",
@@ -12,7 +12,7 @@
     {
       "name": "nber-cli",
       "description": "Use NBER-CLI to search, inspect, download, and serve NBER working paper workflows.",
-      "version": "0.2.0",
+      "version": "0.4.0",
       "author": {
         "name": "Song Tan",
         "email": "sepinetam@gmail.com"

nber_cli-0.5.0/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This file is the canonical release history. The English mirror at `docs/en/changelog.md` and the Chinese mirror at `docs/zh/changelog.md` are generated from the same source content and must stay in lock-step. Any release commit updates all three together.
+
+## [Unreleased]
+
+## [0.5.0] - 2026-06-16
+
+### Security
+- RSS feed parsing now uses `defusedxml` to block XML external entity (XXE) and entity expansion attacks.
+- CLI downloads are restricted to the current working directory and its subdirectories by default. Use `nber-cli download --restrict false` to override per invocation. The `download.restrict_dir` config key is stored and validated, but the current CLI default remains `true`.
+- Database `init` and `migrate` paths on macOS and Linux must reside within the user's home directory.
+- Synchronous HTTP requests enforce TLS 1.2 as the minimum version.
+- Selected info/download failure paths now avoid raw exception text; download-log messages and soft database warnings use sanitized summaries or exception class names.
+
+### Added
+- `nber-cli config show` / `get <key>` / `set <key> <value>` / `verify` for inspecting and editing `~/.nber-cli/config.json`.
+- `download.concurrency` configuration option (default `3`) and the `--concurrency` / `-c` CLI flag to cap concurrent downloads.
+- `--restrict true|false` flag on `nber-cli download` to control directory restriction per invocation.
+- `--yes` flag for `nber-cli mcp-server`; the existing `--port` option now requires explicit confirmation when set to a non-default value.
+- `sse` transport for `nber-cli mcp-server`.
+- JSON Schema (`config.schema.json`) for validating `~/.nber-cli/config.json`.
+- Strict raw-configuration validation that reports malformed JSON, invalid section/value types, and schema-minimum violations without silently injecting defaults.
+- Plugin manifests and marketplace metadata now share the package version, and the Claude plugin skill path uses the case-sensitive tracked `./skills/NBER-CLI` directory.
+- Domain invariant validation in all core dataclasses (`NBER`, `NBERSearchResults`, `NBERFeedItem`, `NBERFeedFetchResult`, clean results, and download results).
+- `get_config_value`, `set_config_value`, `read_config`, `write_config`, and `validate_config` exported from the package top level.
+- Paper ID format validation (`w?\d+`) across CLI, download, and MCP entry points.
+- Validation of fetched paper titles, positive citation IDs, and response/request paper-ID agreement before metadata is accepted.
+
+### Changed
+- Replaced legacy `typing.Dict`, `List`, and `Optional` aliases with modern Python 3.11 syntax.
+- Added `mypy` configuration and strengthened type annotations across `cli.py`, `config_store.py`, and `fetcher.py`.
+- `mcp-server` transport name corrected to `streamable-http`; the existing `--port` option now uses `--yes` confirmation for non-default values.
+- Retry loops in `fetcher.py` now use exponential backoff capped at 30 seconds.
+- `feed fetch` skips malformed individual RSS items instead of failing the entire feed.
+- Invalid configured or per-call download concurrency values are rejected or fall back to the documented safe default instead of creating an invalid semaphore.
+- Database schema-changing and data-writing operations reject databases with a future `PRAGMA user_version`; the diagnostic schema-version reader remains read-only.
+- Feed fetching establishes/validates the local schema before the network request, then writes feed items plus fetch history transactionally after the response is parsed; cleanup operations pair schema validation/upgrade and deletion in one SQLite transaction.
+- `download.py` enables `raise_for_status=True` on `ClientSession`.
+- Error handling narrowed to specific network/timeout exception types with preserved exception chains.
+- Removed the info cache hit hint that was printed to stderr on cached `info` lookups.
+
+### Fixed
+- `feed fetch` now tolerates unescaped `<` characters followed by whitespace or a digit in RSS title and description text while keeping strict XML parsing for all other malformed input.
+- RSS parse failures now report their line and column when available, and `feed fetch` reports runtime parse errors with exit code `1` without printing command usage.
+
+## [0.4.0] - 2026-06-04
+
+### Added
+- `nber-cli info --refresh` skips the local `info_cache` and re-fetches the paper from NBER. The new data is written back to the cache when the cache is enabled.
+- `nber-cli info cache --turn-on` / `--turn-off` toggle the `info_cache` lookup globally and persist the state to `~/.nber-cli/config.json`.
+- `nber-cli info cache --set-refresh <N>` sets the cache refresh interval in days. The value is persisted to `~/.nber-cli/config.json` and used as the TTL for every subsequent `info` call. Defaults to `30` days.
+- `nber-cli info cache clear` with `--days`, `--all`, `--start-date`, or `--end-date` mirrors the `feed clean` parameter set, using `last_fetched_at` from the `info_cache` table. `nber-cli info cache clean` is a convenience alias for `clear --all`.
+- `nber-cli info cache` (no sub-action) prints the current cache state, TTL, and cached row count.
+- New `nber_cli.config_store` module: centralised read and write of `~/.nber-cli/config.json` plus the `InfoCacheSettings` dataclass and helpers (`get_info_cache_settings`, `set_info_cache_enabled`, `set_info_cache_ttl_days`).
+- New `nber_cli.info_cache.get_paper_with_info_cache_result` async helper (in the `nber_cli.info_cache` module) that returns an `InfoCacheLookupResult` carrying the `NBER` paper and a `from_cache` flag, so callers (CLI and MCP) can surface a "loaded from cache" hint.
+- Public Python API exports from the package top level: `InfoCacheSettings`, `clear_info_cache`, `count_info_cache`, `get_info_cache_settings`, `get_info_cache_ttl_days`, `is_info_cache_enabled`, `is_info_cache_expired`, `set_info_cache_enabled`, `set_info_cache_ttl_days`, `NBERInfoCacheClearResult`. `InfoCacheLookupResult` and `get_paper_with_info_cache_result` are exposed from the `nber_cli.info_cache` module rather than the package top level; import them as `from nber_cli.info_cache import ...`.
+
+### Changed
+- `~/.nber-cli/config.json` now carries an `info` section: `info.cache_enabled` (default `true`) and `info.cache_ttl_days` (default `30`). Missing or malformed fields fall back to defaults.
+- `info` now prints a one-line stderr hint when the paper was served from the local cache, pointing to `nber-cli info <id> --refresh` for a fresh fetch.
+
+## [0.3.1] - 2026-06-03
+
+### Added
+- `db init` and `db migrate` top-level subcommands replace `feed init` and `feed migrate`. The database is now general-purpose and stores feed cache, behavior logs, and paper metadata cache.
+- `info_cache` table caches paper metadata fetched via `info` and the MCP `get_paper_info` tool. Subsequent lookups return immediately from the cache.
+- `query_log`, `download_log`, and `info_log` tables record search keywords, download outcomes, and paper info lookups for later auditing.
+- `schema_version` field written to `~/.nber-cli/config.json` so future schema migrations can roll forward safely.
+
+### Changed
+- Default database renamed from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations continue to work without manual steps.
+- Database schema upgraded from `user_version = 1` to `user_version = 2`. Existing v1 databases are upgraded automatically on next CLI invocation; original `feed_items` rows are preserved.
+- Database code consolidated into `nber_cli.db`. The original `init_feed_database`, `migrate_feed_database`, and `get_feed_database_path` helpers are kept as thin compatibility wrappers.
+
+## [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
+- `download` subcommand: single paper ID or batch mode (`--batch`), explicit file path (`--file`), target directory (`--save-base`).
+- `info` subcommand: paper metadata with `--all` flag for full details and `--format json` option.
+- `search` subcommand: full-text search with date filters (`--start-date`, `--end-date`), pagination (`--page`, `--per-page`), `--format json` option.
+- `mcp-server` subcommand: MCP server for AI agent integration with stdio and streamable_http transports.
+
+### Changed
+- Reworked CLI into subcommand syntax (`nber-cli <subcommand>`).
+- Simplified downloader to direct async HTTP PDF fetches (removed database-backed state tracking).
+- Removed legacy web UI module and script entrypoint.
+
+## [0.1.4] - 2025-08-09
+
+### Added
+- Added `--version` / `-v` flag to display current version.
+- Added comprehensive help message with examples.
+- Added `__main__.py` file to support `python -m nber_cli` usage.
+- Added argument grouping for better CLI organization.
+- Added automatic help display when no arguments are provided.

{nber_cli-0.4.0 → nber_cli-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: nber-cli
-Version: 0.4.0
-Summary: A command line interface for reaching the National Bureau of Economic Research (NBER) paper without brower.
+Version: 0.5.0
+Summary: A command-line interface for accessing National Bureau of Economic Research (NBER) papers without a browser.
 Project-URL: Homepage, https://github.com/sepinetam/nber-cli
 Project-URL: Repository, https://github.com/sepinetam/nber-cli
 Project-URL: Issues, https://github.com/sepinetam/nber-cli/issues
@@ -22,6 +22,7 @@ Requires-Python: >=3.11
 Requires-Dist: aiohttp
 Requires-Dist: aiohttp-retry
 Requires-Dist: certifi
+Requires-Dist: defusedxml>=0.7.1
 Requires-Dist: fake-useragent
 Requires-Dist: mcp>=1.27.1
 Description-Content-Type: text/markdown
@@ -33,6 +34,8 @@ A command line interface for reaching the National Bureau of Economic Research (
 [![Lint](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml)
 [![Docs](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/nber-cli.svg)](https://pypi.org/project/nber-cli/)
+[![PyPI Downloads](https://static.pepy.tech/badge/nber-cli)](https://pepy.tech/projects/nber-cli)
 
 [简体中文](README.zh-CN.md) | [Documentation](docs/en/index.md)
 
@@ -43,9 +46,14 @@ A command line interface for reaching the National Bureau of Economic Research (
 - Search NBER working papers by title, paper number, author, abstract, or keyword.
 - Fetch structured metadata and abstracts for a paper ID such as `w25000`.
 - Download single papers or batches as PDF files.
+- Track newly released NBER working papers through a local RSS feed cache (`nber-cli feed fetch` / `feed clean`).
+- Cache paper metadata locally (`nber-cli info` writes to `info_cache`) with a sliding TTL, plus a behavior log for `search`, `download`, and `info` lookups.
+- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db` (path configurable via `nber-cli db init` / `db migrate`).
 - Expose the same core workflows as MCP tools for AI agents.
 - Return human-readable output by default, with JSON output for automation.
 
+See [Configuration](docs/en/configuration.md) for the full list of configurable values and the local database layout, and [Usage Policy](docs/en/policy.md) for what NBER-CLI writes to disk by default.
+
 ## Quick Start
 
 ### Use in Agents

{nber_cli-0.4.0 → nber_cli-0.5.0}/README.md

@@ -5,6 +5,8 @@ A command line interface for reaching the National Bureau of Economic Research (
 [![Lint](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml)
 [![Docs](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/nber-cli.svg)](https://pypi.org/project/nber-cli/)
+[![PyPI Downloads](https://static.pepy.tech/badge/nber-cli)](https://pepy.tech/projects/nber-cli)
 
 [简体中文](README.zh-CN.md) | [Documentation](docs/en/index.md)
 
@@ -15,9 +17,14 @@ A command line interface for reaching the National Bureau of Economic Research (
 - Search NBER working papers by title, paper number, author, abstract, or keyword.
 - Fetch structured metadata and abstracts for a paper ID such as `w25000`.
 - Download single papers or batches as PDF files.
+- Track newly released NBER working papers through a local RSS feed cache (`nber-cli feed fetch` / `feed clean`).
+- Cache paper metadata locally (`nber-cli info` writes to `info_cache`) with a sliding TTL, plus a behavior log for `search`, `download`, and `info` lookups.
+- Store the cache, RSS items, and behavior logs in a local SQLite database at `~/.nber-cli/nber.db` (path configurable via `nber-cli db init` / `db migrate`).
 - Expose the same core workflows as MCP tools for AI agents.
 - Return human-readable output by default, with JSON output for automation.
 
+See [Configuration](docs/en/configuration.md) for the full list of configurable values and the local database layout, and [Usage Policy](docs/en/policy.md) for what NBER-CLI writes to disk by default.
+
 ## Quick Start
 
 ### Use in Agents

{nber_cli-0.4.0 → nber_cli-0.5.0}/README.zh-CN.md

@@ -5,7 +5,8 @@
 [![Lint](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/lint.yml)
 [![Docs](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml/badge.svg)](https://github.com/sepinetam/nber-cli/actions/workflows/docs.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-
+[![PyPI version](https://img.shields.io/pypi/v/nber-cli.svg)](https://pypi.org/project/nber-cli/)
+[![PyPI Downloads](https://static.pepy.tech/badge/nber-cli)](https://pepy.tech/projects/nber-cli)
 [English](README.md) | [中文文档](docs/zh/index.md)
 
 > **NBER** 是 [美国国家经济研究局](https://www.nber.org)（National Bureau of Economic Research）的注册商标。本项目是独立的开源工具，与美国国家经济研究局**不存在任何附属、认可或赞助关系**。使用本项目即视为同意[使用政策](docs/zh/policy.md)。
@@ -15,9 +16,14 @@
 - 按标题、论文编号、作者、摘要或关键词搜索 NBER 工作论文。
 - 通过 `w25000` 这样的论文编号获取结构化元数据和摘要。
 - 下载单篇或批量论文 PDF。
+- 通过本地 RSS feed 缓存追踪 NBER 新发布的工作论文（`nber-cli feed fetch` / `feed clean`）。
+- 本地缓存论文元数据（`nber-cli info` 会写入 `info_cache`），采用滑动 TTL；同时为 `search`、`download` 和 `info` 查询记录行为日志。
+- 把缓存、RSS 条目和行为日志统一存放在本地 SQLite 数据库 `~/.nber-cli/nber.db`（路径可通过 `nber-cli db init` / `db migrate` 配置）。
 - 通过 MCP 工具把核心能力暴露给 AI Agent。
 - 默认输出适合阅读的文本，也支持 JSON 输出用于自动化流程。
 
+完整可配置项和本地数据库结构请见[配置](docs/zh/configuration.md)，默认写入磁盘的内容请见[使用政策](docs/zh/policy.md)。
+
 ## 快速开始
 
 ### 在 Agent 中使用

{nber_cli-0.4.0 → nber_cli-0.5.0}/docs/en/agents/index.md

@@ -33,7 +33,7 @@ Agents that support MCP can run NBER-CLI without a checked-out repository:
 Agents that support skills should load the NBER-CLI skill from:
 
 ```text
-plugins/nber-cli/skills/nber-cli/SKILL.md
+plugins/nber-cli/skills/NBER-CLI/SKILL.md
 ```
 
 The skill tells the agent when to use NBER-CLI, how to run `uvx nber-cli ...`, how to configure MCP, and how to interpret access errors.

{nber_cli-0.4.0 → nber_cli-0.5.0}/docs/en/agents/openclaw.md

@@ -24,7 +24,7 @@ This runs the published `nber-cli` package with `uvx`, so a checked-out copy of
 If OpenClaw supports skill or instruction imports, load:
 
 ```text
-plugins/nber-cli/skills/nber-cli/SKILL.md
+plugins/nber-cli/skills/NBER-CLI/SKILL.md
 ```
 
 The skill gives the agent the usage policy, command examples, JSON output guidance, and common error interpretation.

{nber_cli-0.4.0 → nber_cli-0.5.0}/docs/en/agents/others.md

@@ -20,7 +20,7 @@ Add this MCP server:
 Then load or paste the skill from:
 
 ```text
-plugins/nber-cli/skills/nber-cli/SKILL.md
+plugins/nber-cli/skills/NBER-CLI/SKILL.md
 ```
 
 ## If MCP Is Not Supported

nber_cli-0.5.0/docs/en/changelog.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+This page mirrors the canonical `CHANGELOG.md` at the repository root. The Chinese mirror at `docs/zh/changelog.md` carries the same content. Any release commit updates all three together.
+
+## Unreleased
+
+## 0.5.0 - 2026-06-16
+
+### Security
+
+- RSS feed parsing now uses `defusedxml` to block XML external entity (XXE) and entity expansion attacks.
+- CLI downloads are restricted to the current working directory and its subdirectories by default. Use `nber-cli download --restrict false` to override per invocation. The `download.restrict_dir` config key is stored and validated, but the current CLI default remains `true`.
+- Database `init` and `migrate` paths on macOS and Linux must reside within the user's home directory.
+- Synchronous HTTP requests enforce TLS 1.2 as the minimum version.
+- Selected info/download failure paths now avoid raw exception text; download-log messages and soft database warnings use sanitized summaries or exception class names.
+
+### Added
+
+- Added `nber-cli config show` / `get <key>` / `set <key> <value>` / `verify` for inspecting and editing `~/.nber-cli/config.json`.
+- Added `download.concurrency` configuration option (default `3`) and the `--concurrency` / `-c` CLI flag to cap concurrent downloads.
+- Added `--restrict true|false` flag on `nber-cli download` to control directory restriction per invocation.
+- Added `--yes` for `nber-cli mcp-server`; the existing `--port` option now requires explicit confirmation when set to a non-default value.
+- Added the `sse` transport for `nber-cli mcp-server`.
+- Added JSON Schema (`config.schema.json`) for validating `~/.nber-cli/config.json`.
+- Added strict raw-configuration validation that reports malformed JSON, invalid section/value types, and schema-minimum violations without silently injecting defaults.
+- Added plugin manifest and marketplace metadata version synchronization, with the Claude plugin skill path corrected to the case-sensitive tracked `./skills/NBER-CLI` directory.
+- Added domain invariant validation in all core dataclasses (`NBER`, `NBERSearchResults`, `NBERFeedItem`, `NBERFeedFetchResult`, clean results, and download results).
+- Added `get_config_value`, `set_config_value`, `read_config`, `write_config`, and `validate_config` exports from the package top level.
+- Added paper ID format validation (`w?\d+`) across CLI, download, and MCP entry points.
+- Added validation of fetched paper titles, positive citation IDs, and response/request paper-ID agreement before metadata is accepted.
+
+### Changed
+
+- Replaced legacy `typing.Dict`, `List`, and `Optional` aliases with modern Python 3.11 syntax.
+- Added `mypy` configuration and strengthened type annotations across `cli.py`, `config_store.py`, and `fetcher.py`.
+- Corrected the `mcp-server` transport name to `streamable-http`; the existing `--port` option now uses `--yes` confirmation for non-default values.
+- Retry loops in `fetcher.py` now use exponential backoff capped at 30 seconds.
+- `feed fetch` skips malformed individual RSS items instead of failing the entire feed.
+- Invalid configured or per-call download concurrency values are rejected or fall back to the documented safe default instead of creating an invalid semaphore.
+- Database schema-changing and data-writing operations reject databases with a future `PRAGMA user_version`; the diagnostic schema-version reader remains read-only.
+- Feed fetching establishes/validates the local schema before the network request, then writes feed items plus fetch history transactionally after the response is parsed; cleanup operations pair schema validation/upgrade and deletion in one SQLite transaction.
+- `download.py` enables `raise_for_status=True` on `ClientSession`.
+- Error handling narrowed to specific network/timeout exception types with preserved exception chains.
+- Removed the info cache hit hint that was printed to stderr on cached `info` lookups.
+
+### Fixed
+
+- `feed fetch` now tolerates unescaped `<` characters followed by whitespace or a digit in RSS title and description text while keeping strict XML parsing for all other malformed input.
+- RSS parse failures now report their line and column when available, and `feed fetch` reports runtime parse errors with exit code `1` without printing command usage.
+
+## 0.4.0 - 2026-06-04
+
+### Added
+
+- Added `nber-cli info --refresh` to bypass the local `info_cache` and re-fetch paper metadata from NBER. The fresh data is written back to the cache when the cache is enabled.
+- Added `nber-cli info cache --turn-on` and `--turn-off` to toggle the `info_cache` lookup globally. The setting is persisted to `~/.nber-cli/config.json`.
+- Added `nber-cli info cache --set-refresh <N>` to set the cache refresh interval in days. The value is persisted to `~/.nber-cli/config.json` and applied as the TTL for every subsequent `info` call. Defaults to `30` days.
+- Added `nber-cli info cache clear` with the same parameter set as `feed clean`: `--days`, `--all`, `--start-date`, and `--end-date`. Filtering uses `last_fetched_at` from the `info_cache` table. `nber-cli info cache clean` is a convenience alias for `clear --all`.
+- Added `nber-cli info cache` (no sub-action) to print the current cache state, TTL, and cached row count.
+- Added `nber_cli.config_store` module with `InfoCacheSettings` and helpers (`get_info_cache_settings`, `set_info_cache_enabled`, `set_info_cache_ttl_days`) for reading and writing `~/.nber-cli/config.json`.
+- Added `nber_cli.info_cache.get_paper_with_info_cache_result` async helper that returns an `InfoCacheLookupResult` carrying the `NBER` paper and a `from_cache` flag.
+- Added public Python API exports from the package top level: `InfoCacheSettings`, `clear_info_cache`, `count_info_cache`, `get_info_cache_settings`, `get_info_cache_ttl_days`, `is_info_cache_enabled`, `is_info_cache_expired`, `set_info_cache_enabled`, `set_info_cache_ttl_days`, `NBERInfoCacheClearResult`. `InfoCacheLookupResult` and `get_paper_with_info_cache_result` are exposed from the `nber_cli.info_cache` module rather than the package top level; import them as `from nber_cli.info_cache import ...`.
+
+### Changed
+
+- `~/.nber-cli/config.json` now stores an `info` section: `info.cache_enabled` (default `true`) and `info.cache_ttl_days` (default `30`). Missing or malformed fields fall back to defaults.
+- `info` now prints a one-line stderr hint when the paper was served from the local cache, pointing to `nber-cli info <id> --refresh` for a fresh fetch.
+
+## 0.3.1 - 2026-06-03
+
+### Added
+
+- Added `nber-cli db init` and `nber-cli db migrate` for initializing and relocating the local database. These replace `feed init` and `feed migrate`.
+- Added `info_cache` table so repeated `nber-cli info` and MCP `get_paper_info` calls return immediately from cache.
+- Added `query_log`, `download_log`, and `info_log` tables for recording search keywords, download outcomes, and info lookups.
+- Added `schema_version` field in `~/.nber-cli/config.json` for forward-compatible schema upgrades.
+
+### Changed
+
+- Renamed default database file from `feed.db` to `nber.db`. Existing `~/.nber-cli/feed.db` installations keep working without manual steps.
+- Upgraded database schema from version 1 to version 2 with automatic upgrade on next invocation.
+- Consolidated database code into `nber_cli.db`. Old `init_feed_database` and `migrate_feed_database` helpers remain as thin compatibility wrappers.
+
+## 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-31
+
+### Changed
+
+- Reworked the CLI into `nber-cli download ...` subcommand syntax.
+- Added `--file/-f` and `--save-base/-s` path handling behavior.
+- Added `--batch/-b` multi-ID download mode.
+- Removed database-backed download state tracking.
+- Simplified the downloader to direct async HTTP PDF fetches.
+- Updated documentation for the v0.2 command model.
+- Removed the legacy web UI module and script entrypoint.
+
+## 0.1.4 - 2025-08-09
+
+### Added
+
+- Added `--version` / `-v` flag to display current version.
+- Added comprehensive help message with examples.
+- Added `__main__.py` support for `python -m nber_cli`.
+- Added argument grouping for better CLI organization.
+- Added automatic help display when no arguments are provided.

{nber_cli-0.4.0 → nber_cli-0.5.0}/docs/en/cli.md

@@ -72,6 +72,17 @@ nber-cli download -b w34567 w25000 w32000 -s ~/papers/nber
 - If neither `--file` nor `--save-base` is passed, PDFs are saved in the current working directory.
 - If a paper is unavailable, NBER-CLI exits with code `1` and prints a readable error message.
 
+### download Filesystem Behavior
+
+- **Existing files are overwritten.** When the target PDF path already exists, NBER-CLI writes the new bytes in place and overwrites the previous file. There is no "skip if newer" or "preserve on error" mode.
+- **No atomic rename.** The download is read fully into memory and then written to the target path in a single `write_bytes` call. If the process is killed, the host loses power, or the disk fills up mid-write, the file at the target path can be left empty, truncated, or partially written. The previous file (when it existed) is not preserved on the failure path.
+- **Parent directories are auto-created.** The parent of the resolved output path is created with `mkdir(parents=True, exist_ok=True)`. Missing intermediate directories do not cause a failure, but the process needs write permission on the deepest existing ancestor.
+- **Path resolution is literal.** The string passed to `--file` (or `<paper_id>.pdf` derived from `--save-base`) is used verbatim. Relative paths resolve against the current working directory. Tilde expansion (`~`) is **not** performed; if you want `~`-relative paths, your shell needs to expand them.
+- **Single download is fully in-memory.** The full PDF body is buffered before any disk write, so a single download holds the entire PDF in memory for the duration of the transfer. Very large PDFs may briefly use several hundred MB of RAM.
+- **Python API callers own their session.** When you call `download_paper` / `download_paper_to_file` / `download_multiple_papers` with a custom `session=...`, you own the underlying `ClientSession` (or `RetryClient`), its timeouts, its connector limits, and any retry behavior. NBER-CLI does not wrap your session in a retry client. The default NBER_CLI_CONFIG timeout and retry settings only apply when the function creates its own session.
+
+For the Python API, see [Python API — Download PDF](python-api.md#download-a-pdf).
+
 ## info
 
 Show paper metadata:
@@ -104,7 +115,9 @@ nber-cli info w25000 -f json
 
 When the cache is enabled and the cached entry has not yet passed the configured TTL, repeated `info` calls are served from the local database. The first `info` call after a TTL expiry, or any call with `--refresh`, performs a live fetch.
 
-The MCP `get_paper_info` tool follows the same cache behavior, including the `--refresh` flag.
+The TTL is **sliding**: every cache hit updates `last_fetched_at` and increments `fetch_count`, so frequently consulted papers keep their cached copy until at least `cache_ttl_days` have passed since the most recent hit. "Last fetched" therefore means "last local hit", not "last network fetch from NBER". `--refresh` always bypasses the cache and writes a fresh row.
+
+The MCP `get_paper_info` tool follows the same cache behavior, but it does not accept a per-call `--refresh` argument. The tool always honors the current `info_cache` toggle and TTL; agents that need a forced refresh must toggle the cache off, call `get_paper_info`, and toggle the cache back on (or rely on the next call after a TTL-driven re-fetch).
 
 ## info cache
 
@@ -114,8 +127,11 @@ Show the current cache state, TTL, and row count:
 
 ```bash
 nber-cli info cache
+nber-cli info cache status
 ```
 
+`info cache` and `info cache status` are equivalent — both print the same status view (cache enabled/disabled, current TTL, and row count). The explicit `status` sub-action is provided for symmetry with `clear`/`clean` and for scripts that prefer an unambiguous form.
+
 Toggle the cache globally:
 
 ```bash
@@ -174,6 +190,7 @@ Only `y` or `Y` continues. Any other response aborts without deleting records.
 | (none) | `--turn-on` | Enable the info cache globally. |
 | (none) | `--turn-off` | Disable the info cache globally. |
 | (none) | `--set-refresh` | Set the info cache refresh interval in days. Must be a positive integer. |
+| `status` | — | Print the current cache state, TTL, and row count. Equivalent to running `info cache` with no sub-action. |
 | `clear` | `--days` | Clean cached records not refreshed for this many days. Defaults to `30`. |
 | `clear` | `--all` | Clean all cached records. |
 | `clear` | `--start-date` | Clean cached records refreshed on or after this date, formatted `YYYY-MM-DD`. |
@@ -239,6 +256,8 @@ nber-cli feed fetch --display-all true
 nber-cli feed fetch --display-all
 ```
 
+`--display-all` accepts a boolean value. The parser recognises (case-insensitive, whitespace tolerated) `true`, `false`, `1`, `0`, `yes`, `no`, `y`, `n`, `on`, `off`. When the flag is passed with no value (`--display-all` on its own) it defaults to `true`. Any other value is rejected with exit code `2`.
+
 Limit displayed output:
 
 ```bash
@@ -254,6 +273,8 @@ nber-cli feed fetch --format json
 nber-cli feed fetch -f json
 ```
 
+NBER-CLI strictly parses the RSS XML. To tolerate a known upstream formatting issue, it repairs only unescaped `<` characters followed by whitespace or a digit inside RSS `title` and `description` text. Other malformed XML is rejected. Parse errors exit with code `1`, print a concise error with the line and column when available, and do not print command usage.
+
 ### 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.
@@ -294,7 +315,7 @@ Only `y` or `Y` continues. Any other response aborts without deleting records.
 
 | Subcommand | Option | Description |
 | --- | --- | --- |
-| `fetch` | `--display-all [true|false]` | Display all fetched RSS items instead of only new items. |
+| `fetch` | `--display-all [true\|false]` | Display all fetched RSS items instead of only new items. Accepts `true`/`false`/`1`/`0`/`yes`/`no`/`y`/`n`/`on`/`off` (case-insensitive). When passed without a value, defaults to `true`. |
 | `fetch` | `--format`, `-f` | Output format: `list` or `json`. Defaults to `list`. |
 | `fetch` | `--max-items` | Maximum number of feed items to display. |
 | `clean` | `--days` | Clean cached records not seen for this many days. Defaults to `30`. |
@@ -364,9 +385,25 @@ For client configuration and tool details, see [MCP Server](mcp.md).
 | Code | Meaning |
 | --- | --- |
 | `0` | Command completed successfully, or help was printed. |
-| `1` | Runtime failure such as a failed download. |
-| `2` | Invalid command-line arguments. |
+| `1` | Runtime failure such as a failed download, a network error, a parse error, or any other unhandled exception. |
+| `2` | Invalid command-line arguments. Argparse raises `SystemExit(2)` and prints a usage message to stderr. |
+
+A few extra rules that are easy to miss:
+
+- A single `download` failure exits `1`. The successful `Successfully downloaded <id> to <path>` line goes to stdout; the `Failed to download <id>: <reason>` line goes to stderr. The download log row in `download_log` is written before the failure is printed.
+- A batch `download` runs every requested paper and only exits `1` at the end if at least one paper failed. Successful files are written to stdout (`Successfully downloaded ...`), failures and the per-failure reasons go to stderr. The exit code is `0` only when every paper succeeded.
+- A `feed fetch` RSS parse failure exits `1` and writes a concise error to stderr without printing command usage. The error includes the XML line and column when available.
+- `db init`, `db migrate`, `info cache clear`, and `feed clean` print a confirmation prompt to stderr. The command aborts with exit code `0` if the user declines (`Abort.` is printed to stderr). The actual deletion (when confirmed) exits `0` on success.
+- Database record-keeping failures (`record_query`, `record_download`, `record_info`, `touch_info_cache`, `write_info_cache`) print a one-line `warning: failed to ...` to stderr but do **not** raise. The main command's exit code is unaffected.
+- The download module reads the entire PDF body into memory and then writes it in one call. A failure that occurs between the network read and the disk write (process kill, disk full, permission revoked) typically surfaces as a Python exception on the way out; the user sees the traceback on stderr and the process exits `1`. There is no atomic-rename guarantee, so a target file may be left empty or partially written when this happens.
 
 ## Output Formats
 
 `info`, `search`, and `feed fetch` default to `list`, a readable text format. Use `--format json` when piping output into scripts or agent workflows.
+
+The rule of thumb for scripting:
+
+- **stdout** carries the human-readable output or the JSON payload (with `--format json`).
+- **stderr** carries the cache-hit hint, every per-paper error message, every per-paper success line that is incidental to the main payload, the `warning: ...` line for failed background logging, and the confirmation prompts for destructive commands.
+
+This means a script that wants the JSON payload can capture stdout with `2>/dev/null` (or simply `2>&-`), and a script that wants only errors can capture stderr with `2>&1 >/dev/null`.