jfox-cli 1.0.0__tar.gz → 1.1.1__tar.gz

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/.claude-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "JFox Zettelkasten 知识管理工具的 Claude Code 集成",
-    "version": "0.2.0"
+    "version": "0.3.0"
   },
   "plugins": [
     {
       "name": "jfox",
       "source": "./packages/cc-plugin",
       "description": "JFox 知识管理 CLI 的 Claude Code 集成——搜索、写入工作流（导入/整理/会话总结）与知识库管理",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "author": { "name": "zhuxixi" },
       "keywords": ["zettelkasten", "knowledge-management"],
       "category": "workflow"

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/.gitignore

@@ -42,6 +42,7 @@ cache/
 .claude/scheduled_tasks.json
 .claude/scheduled_tasks.lock
 .claude/worktrees/
+.claude/settings.local.json
 
 # Temporary analysis files
 analysis_report.md

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/AGENTS.md

@@ -46,6 +46,7 @@ jfox/
 │   ├── kb_manager.py          # 知识库管理器
 │   ├── embedding_backend.py   # 嵌入模型后端（支持 daemon 代理）
 │   ├── daemon/                # Embedding 模型 HTTP 守护进程
+│   ├── fragment/              # 碎片采集（Hook → daemon API → SQLite）
 │   ├── vector_store.py        # ChromaDB 向量存储
 │   ├── bm25_index.py          # BM25 关键词索引
 │   ├── search_engine.py       # 混合搜索引擎（RRF 融合）
@@ -161,6 +162,7 @@ uv run jfox --version
 | `note_index.py` | 笔记索引管理（文件名↔ID 映射） |
 | `indexer.py` | 文件监控（watchdog）+ 增量索引 |
 | `daemon/` | Embedding 模型 HTTP 守护进程（server/client/process） |
+| `fragment/` | 碎片采集：detector 分类 + store SQLite + service 编排 |
 
 ### 笔记类型
 

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.1.1] - 2026-06-21
+
+### Features
+- Claude Code Hook 碎片采集（#261 Phase 1） (#269)
+
+### Fixes
+- **update**: 已是最新版本时显示正确提示 (#268)
+
+### Changes
+- gitignore .claude/settings.local.json and untrack it (#266)
+
+[1.1.1]: https://github.com/zhuxixi/jfox/compare/v1.1.0...v1.1.1
+
+## [1.1.0] - 2026-06-21
+
+### Features
+- **cli**: add self-update command (#258)
+- 笔记归档/软删除功能（archive/unarchive） (#260)
+
+### Fixes
+- **cli**: jfox index rebuild --backlinks recalculates wiki links and backlinks
+
+[1.1.0]: https://github.com/zhuxixi/jfox/compare/v1.0.0...v1.1.0
+
 ## [1.0.0] - 2026-06-18
 
 ### Features

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/CLAUDE.md

@@ -71,6 +71,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 | `bm25_index.py` | BM25 keyword search index |
 | `embedding_backend.py` | Sentence-transformers embedding backend（支持 daemon 代理） |
 | `daemon/` | Embedding 模型 HTTP 守护进程 (`server.py`/`client.py`/`process.py`)，`jfox daemon start/stop/status` |
+| `fragment/` | 碎片采集：detector 分类 + store SQLite(WAL) + service 编排 |
 | `vector_store.py` | ChromaDB vector store for semantic search |
 | `graph.py` | NetworkX knowledge graph from links/backlinks |
 | `template.py` / `template_cli.py` | Jinja2 template system for structured note creation |

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 1.0.0
+Version: 1.1.1
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox
@@ -392,6 +392,13 @@ A session is considered "finished" when its file has not been modified for `idle
 
 > **Privacy note:** Auto-summary sends session text to Anthropic API via `claude -p` to generate summaries. Only session content is transmitted.
 
+### Self-Update
+
+| Command | Description |
+|---------|-------------|
+| `jfox update` | Upgrade jfox to the latest version (auto-detects pip/pipx/uv) |
+| `jfox update --json` | JSON output with before/after version info |
+
 ### Global Options
 
 | Option | Description |

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/README.md

@@ -353,6 +353,13 @@ A session is considered "finished" when its file has not been modified for `idle
 
 > **Privacy note:** Auto-summary sends session text to Anthropic API via `claude -p` to generate summaries. Only session content is transmitted.
 
+### Self-Update
+
+| Command | Description |
+|---------|-------------|
+| `jfox update` | Upgrade jfox to the latest version (auto-detects pip/pipx/uv) |
+| `jfox update --json` | JSON output with before/after version info |
+
 ### Global Options
 
 | Option | Description |

{jfox_cli-1.0.0 → jfox_cli-1.1.1}/docs/installation.md

@@ -28,6 +28,32 @@ jfox --version
 pip install -e ".[dev]"
 ```
 
+## Upgrade
+
+```bash
+# Auto-detect installation method and upgrade
+jfox update
+
+# JSON output with version info
+jfox update --json
+```
+
+If `jfox update` fails (e.g. behind a proxy or on an unsupported install method), use the manual command for your install method:
+
+```bash
+# uv tool users
+uv tool upgrade jfox-cli
+
+# pipx users
+pipx upgrade jfox-cli
+
+# pip users
+pip install --upgrade jfox-cli
+
+# Development mode (git clone + uv sync --extra dev)
+git pull && uv sync --extra dev
+```
+
 ## Uninstall
 
 ```bash

jfox_cli-1.1.1/docs/superpowers/plans/2026-06-17-index-rebuild-backlinks.md

@@ -0,0 +1,166 @@
+# Issue #252: `jfox index rebuild` 重新计算 backlinks Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 让 `jfox index rebuild` 支持 `--backlinks` 选项，在重建索引时重新解析 wiki links 并计算 backlinks。
+
+**Architecture:** 在 `jfox/cli.py` 中新增 `_rebuild_backlinks_impl()` 内部函数，在 `index rebuild` action 中按用户传入的 `--backlinks` 标志调用；函数全量加载笔记、解析 `[[...]]` 链接、解析目标 ID、重新计算并写回变化的笔记。
+
+**Tech Stack:** Python, Typer, pytest
+
+---
+
+### Task 1: 实现 `_rebuild_backlinks_impl()` 内部函数
+
+**Files:**
+- Modify: `jfox/cli.py`（在 `extract_wiki_links` / `find_note_id_by_title_or_id` 附近或 `_add_note_impl` 之后新增函数）
+
+- [ ] **Step 1: 编写核心函数**
+
+  新增函数签名：
+  ```python
+  def _rebuild_backlinks_impl(output_format: str = "table") -> Dict[str, Any]:
+      ...
+  ```
+
+  功能：
+  1. 调用 `note.list_notes(limit=10000)` 加载所有笔记
+  2. 遍历笔记，调用 `extract_wiki_links(note.content)` 提取链接
+  3. 调用 `find_note_id_by_title_or_id(link_text)` 解析目标 ID
+  4. 构建 `new_links: Dict[str, List[str]]` 和 `new_backlinks: Dict[str, List[str]]`
+  5. 对每个笔记，比较现有 `links`/`backlinks` 与新计算结果
+  6. 如有变化，更新 Note 对象并调用 `note.save_note(note, add_to_index=False)`
+  7. 返回统计信息：`backlinks_rebuilt`, `backlinks_updated`, `backlinks_total`, `unresolved_links`
+
+- [ ] **Step 2: 处理边界情况**
+
+  - 空知识库：返回 `backlinks_total=0`, `backlinks_updated=0`
+  - 未解析链接：收集到 `unresolved_links` 列表中用于警告输出
+  - 保存失败：记录 warning，不中断流程
+
+---
+
+### Task 2: 在 `index rebuild` action 中集成 `--backlinks` 选项
+
+**Files:**
+- Modify: `jfox/cli.py:index()` 命令参数
+- Modify: `jfox/cli.py` 中 `action == "rebuild"` 分支
+
+- [ ] **Step 1: 添加 Typer 选项**
+
+  在 `index()` 命令中新增：
+  ```python
+  backlinks: bool = typer.Option(False, "--backlinks", "-b", help="重建时重新计算 backlinks"),
+  ```
+
+- [ ] **Step 2: 在 rebuild action 中调用**
+
+  在 `action == "rebuild"` 分支中，BM25 重建完成后：
+  ```python
+  if backlinks:
+      bl_result = _rebuild_backlinks_impl(output_format)
+      result.update(bl_result)
+  ```
+
+- [ ] **Step 3: 更新输出**
+
+  JSON 输出：合并 `backlinks_rebuilt`, `backlinks_updated`, `backlinks_total`, `unresolved_links`
+  Table 输出：增加对应行，显示 `Backlinks rebuilt: X / Y`，以及未解析链接警告
+
+---
+
+### Task 3: 编写测试
+
+**Files:**
+- New: `tests/integration/test_index_rebuild_backlinks.py`
+- New: `tests/unit/test_rebuild_backlinks_impl.py`
+
+- [ ] **Step 1: 编写集成测试**
+
+  `tests/integration/test_index_rebuild_backlinks.py`：
+  - 使用 `cli` fixture 初始化临时知识库
+  - 创建目标笔记 A 和源笔记 B（B 引用 A）
+  - 手动修改 A 的 frontmatter，移除其 `backlinks`
+  - 执行 `cli.index("rebuild", "--backlinks")`
+  - 验证 `refs A` 的 `backward_links` 包含 B
+  - 验证 JSON 输出中的 `backlinks_updated > 0`
+
+- [ ] **Step 2: 编写单元测试**
+
+  `tests/unit/test_rebuild_backlinks_impl.py`：
+  - Mock `note.list_notes()` 返回若干笔记对象
+  - 调用 `_rebuild_backlinks_impl()`
+  - 验证统计信息正确
+  - 验证 `save_note` 只在变化时调用
+
+- [ ] **Step 3: 验证默认行为不变**
+
+  集成测试增加：
+  - 默认 `jfox index rebuild`（无 `--backlinks`）不应修改任何笔记的 backlinks
+
+---
+
+### Task 4: 运行测试与代码检查
+
+- [ ] **Step 1: 运行新增单元测试**
+
+  ```bash
+  uv run pytest tests/unit/test_rebuild_backlinks_impl.py -v
+  ```
+
+- [ ] **Step 2: 运行新增集成测试**
+
+  ```bash
+  uv run pytest tests/integration/test_index_rebuild_backlinks.py -v
+  ```
+
+- [ ] **Step 3: 运行快速测试集**
+
+  ```bash
+  uv run pytest tests/ -m "not embedding and not slow" -q
+  ```
+
+- [ ] **Step 4: 代码风格检查**
+
+  ```bash
+  uv run ruff check jfox/cli.py tests/unit/test_rebuild_backlinks_impl.py tests/integration/test_index_rebuild_backlinks.py
+  uv run black --check jfox/cli.py tests/unit/test_rebuild_backlinks_impl.py tests/integration/test_index_rebuild_backlinks.py
+  ```
+
+---
+
+### Task 5: 提交与 PR
+
+- [ ] **Step 1: 整理提交**
+
+  使用 Conventional Commits：
+  ```bash
+  git add jfox/cli.py tests/unit/test_rebuild_backlinks_impl.py tests/integration/test_index_rebuild_backlinks.py docs/superpowers/specs/2026-06-17-index-rebuild-backlinks-design.md docs/superpowers/plans/2026-06-17-index-rebuild-backlinks.md
+  git commit -m "fix(cli): jfox index rebuild --backlinks recalculates wiki links and backlinks
+
+  - Add --backlinks/-b option to jfox index rebuild
+  - Add _rebuild_backlinks_impl() to parse [[...]] links and recompute backlinks
+  - Update output JSON/table with backlinks rebuild stats
+  - Add unit and integration tests
+
+  Closes #252"
+  ```
+
+- [ ] **Step 2: 推送分支**
+
+  ```bash
+  git push origin fix/252-index-rebuild-backlinks
+  ```
+
+- [ ] **Step 3: 创建 PR**
+
+  PR 标题：`fix(cli): jfox index rebuild --backlinks recalculates wiki links and backlinks`
+  PR 描述包含：
+  - 问题描述
+  - 修改内容
+  - 测试说明
+  - `Closes #252`
+
+- [ ] **Step 4: 等待 CI 通过**
+
+  在 PR 页面确认 Fast / Core workflow 通过。

jfox_cli-1.1.1/docs/superpowers/plans/2026-06-18-self-update-command.md

@@ -0,0 +1,175 @@
+# jfox self-update 命令 Implementation Plan
+
+> **For agentic workers:** implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `jfox update` command that detects the current installation method (dev / uv / pipx / pip) and invokes the appropriate upgrade command, showing before/after version info and providing manual fallback guidance on failure.
+
+**Architecture:** A new `update` Typer command in `jfox/cli.py` plus helper functions for install-method detection and upgrade command execution. Detection is path-based with command fallbacks. A unit test file `tests/unit/test_update.py` mocks filesystem paths and subprocess calls.
+
+**Tech Stack:** Python 3.10+, Typer, Rich, pytest, unittest.mock.
+
+**Spec:** `docs/superpowers/specs/2026-06-18-self-update-command-design.md`
+
+**Work context:** Work in the isolated worktree `/home/elling/git-repo/github/jfox-wt-238` on branch `feat/issue-238-self-update` (based off `main`). All paths below are relative to that worktree root.
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|------|--------|----------------|
+| `jfox/cli.py` | **Modify** | Add `_detect_install_method`, `_build_upgrade_command`, `_run_upgrade`, `_update_impl`, and `update` Typer command. |
+| `tests/unit/test_update.py` | **Create** | Unit tests for detection, command selection, JSON output, dev-mode prompt, and failure handling. |
+| `README.md` | **Modify** | Add `jfox update` to the command reference table. |
+| `docs/installation.md` | **Modify** | Add an "Upgrade" section with `jfox update` and manual fallbacks. |
+
+---
+
+## Task 1: Implement install-method detection helpers
+
+**Files:** `jfox/cli.py`
+
+- [ ] **Step 1: Add `_is_dev_installation` helper**
+
+  Determine development mode by checking whether `jfox.__file__` resolves to a source tree containing `pyproject.toml` with `project.name == "jfox-cli"` and a `.git` directory, or whether the path indicates an editable install (`.egg-link`).
+
+- [ ] **Step 2: Add `_is_uv_tool_installation` helper**
+
+  Run `uv tool dir` to obtain the uv tools root. Return `True` if `jfox.__file__` is relative to `<uv-tool-dir>/jfox-cli/`. If `uv` is unavailable, fall back to path-segment matching (`uv/tools/jfox-cli/`).
+
+- [ ] **Step 3: Add `_is_pipx_installation` helper**
+
+  Run `pipx environment --value PIPX_HOME` to obtain pipx home. Return `True` if `jfox.__file__` is relative to `<pipx-home>/venvs/jfox-cli/`. If `pipx` is unavailable, fall back to path-segment matching (`pipx/venvs/jfox-cli/`).
+
+- [ ] **Step 4: Add `_detect_install_method` helper**
+
+  Apply the detection order: dev → uv → pipx → pip. Return a string identifier (`"dev"`, `"uv"`, `"pipx"`, `"pip"`).
+
+---
+
+## Task 2: Implement upgrade execution and version comparison
+
+**Files:** `jfox/cli.py`
+
+- [ ] **Step 1: Add `_build_upgrade_command` helper**
+
+  Map the detected install method to the concrete command list:
+  - `"uv"` → `["uv", "tool", "upgrade", "jfox-cli"]`
+  - `"pipx"` → `["pipx", "upgrade", "jfox-cli"]`
+  - `"pip"` → `[sys.executable, "-m", "pip", "install", "--upgrade", "jfox-cli"]`
+  - `"dev"` → return `None`
+
+- [ ] **Step 2: Add `_run_upgrade` helper**
+
+  Use `subprocess.run(..., check=True, capture_output=True, text=True)` to execute the command. On success return stdout; on `CalledProcessError` raise a custom exception or return an error dict. Surface stderr to the user.
+
+- [ ] **Step 3: Add `_get_installed_version` helper**
+
+  Run `jfox --version` via subprocess and parse the version string. Return `"unknown"` if the call fails.
+
+---
+
+## Task 3: Wire up the `update` Typer command
+
+**Files:** `jfox/cli.py`
+
+- [ ] **Step 1: Add `_update_impl` internal function**
+
+  1. Read current `__version__`.
+  2. Detect install method.
+  3. If dev, return a result dict with `success=True`, `method="dev"`, and an instruction string.
+  4. Build and run the upgrade command.
+  5. Call `_get_installed_version` for the after version.
+  6. Return a result dict: `success`, `method`, `previous_version`, `current_version`, `command`, `output`.
+
+- [ ] **Step 2: Add `update` Typer command**
+
+  Support `--format json/table` and `--json` shortcut. Wrap the implementation in a try/except, print table or JSON output, and exit with code 1 on failure.
+
+---
+
+## Task 4: Add unit tests
+
+**Files:** `tests/unit/test_update.py`
+
+- [ ] **Step 1: Test dev-mode detection**
+
+  Mock `jfox.__file__` to a source tree path with `pyproject.toml` and `.git/`. Assert `jfox update` prints the dev-mode instruction and does not invoke subprocess.
+
+- [ ] **Step 2: Test uv / pipx / pip command selection**
+
+  Mock `jfox.__file__` to each tool's typical site-packages path and assert the correct subprocess command is invoked.
+
+- [ ] **Step 3: Test JSON output**
+
+  Run `jfox update --json` and verify the parsed JSON contains expected keys.
+
+- [ ] **Step 4: Test upgrade failure handling**
+
+  Make `subprocess.run` raise `CalledProcessError`. Assert exit code 1 and manual command guidance appears in output/JSON.
+
+- [ ] **Step 5: Test version before/after display**
+
+  Mock `jfox.__version__` and the post-upgrade `jfox --version` subprocess to verify both versions appear.
+
+---
+
+## Task 5: Update documentation
+
+**Files:** `README.md`, `docs/installation.md`
+
+- [ ] **Step 1: Add `jfox update` to README command table**
+
+  Place it under a new "Self-update" row or in the most appropriate existing section.
+
+- [ ] **Step 2: Add upgrade section to `docs/installation.md`**
+
+  Document `jfox update` and the manual fallbacks for each install method.
+
+---
+
+## Task 6: Run tests and static checks
+
+- [ ] **Step 1: Run the new unit tests**
+
+  ```bash
+  uv run pytest tests/unit/test_update.py -v
+  ```
+
+- [ ] **Step 2: Run fast unit tests**
+
+  ```bash
+  uv run pytest tests/unit/ -m "not embedding and not slow" -q
+  ```
+
+- [ ] **Step 3: Run ruff lint**
+
+  ```bash
+  uv run ruff check jfox/cli.py tests/unit/test_update.py
+  ```
+
+---
+
+## Task 7: Commit and create PR
+
+- [ ] **Step 1: Stage and commit changes**
+
+  Use Conventional Commits:
+
+  ```bash
+  git add jfox/cli.py tests/unit/test_update.py README.md docs/installation.md docs/superpowers/
+  git commit -m "feat(cli): add self-update command (jfox update)"
+  git commit -m "docs(readme): document jfox update command" -- README.md docs/installation.md
+  git commit -m "docs(superpowers): add self-update design and plan"
+  ```
+
+- [ ] **Step 2: Push branch and create PR**
+
+  ```bash
+  git push -u origin feat/issue-238-self-update
+  gh pr create --title "feat(cli): add self-update command" --body "Closes #238" --base main
+  ```
+
+- [ ] **Step 3: Wait for CI**
+
+  Monitor the PR checks and address any failures.