jfox-cli 0.7.1__tar.gz → 0.7.2__tar.gz

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [0.7.2] - 2026-05-07
+
+### Fixes
+- **note**: atomic write to prevent 0-byte note files (#201)
+- strip frontmatter from --content-file input to prevent duplication (#200)
+
+### Changes
+- update CLAUDE.md to reflect current codebase state (#203)
+
+[0.7.2]: https://github.com/zhuxixi/jfox/compare/v0.7.1...v0.7.2
+
 ## [0.7.1] - 2026-05-05
 
 ### Fixes

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/CLAUDE.md

@@ -56,18 +56,21 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 
 | Module | Role |
 |--------|------|
-| `cli.py` | All CLI commands (~2500 lines). Commands follow pattern: `@app.command()` → `_xxx_impl()` helper for reuse |
+| `cli.py` | All CLI commands (~2900 lines). Commands follow pattern: `@app.command()` → `_xxx_impl()` helper for reuse |
 | `config.py` | `ZKConfig` + `use_kb()` context manager for multi-KB switching |
 | `global_config.py` | `GlobalConfigManager` managing `~/.zk_config.json` |
 | `kb_manager.py` | Knowledge base lifecycle (create, rename, remove) |
 | `formatters.py` | Output formats: JSON, CSV, YAML, Table, Paths |
+| `git_extractor.py` | Git 仓库数据提取器（ingest 功能） |
+| `model_downloader.py` | Embedding 模型下载与缓存管理 |
+| `note_index.py` | 笔记索引管理（文件名↔ID 映射） |
 | `indexer.py` | File monitoring (watchdog) + incremental indexing |
 | `note.py` | Markdown file CRUD with YAML frontmatter |
 | `models.py` | `Note` data model with frontmatter serialization |
 | `search_engine.py` | `HybridSearchEngine` with `SearchMode` enum, RRF fusion |
 | `bm25_index.py` | BM25 keyword search index |
 | `embedding_backend.py` | Sentence-transformers embedding backend（支持 daemon 代理） |
-| `daemon/` | Embedding 模型 HTTP 守护进程，`jfox daemon start/stop/status` |
+| `daemon/` | Embedding 模型 HTTP 守护进程 (`server.py`/`client.py`/`process.py`)，`jfox daemon start/stop/status` |
 | `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 |
@@ -107,11 +110,11 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 - **Model caching**: Session-level model cache in conftest.py to avoid 30-60s reload per test
 - **Test markers**: `slow`, `performance`, `integration`, `embedding`, `workflow`, `bulk`
 - **Run single-process** to avoid ChromaDB/model loading conflicts
-- **Test directory reorganization in progress**:
-  - `tests/unit/` — Pure logic unit tests (formatters, config, kb_manager, template)
-  - `tests/integration/` — Cross-module integration tests (backlinks)
+- **Test directory reorganization mostly complete**:
+  - `tests/unit/` — Pure logic unit tests (25 files)
+  - `tests/integration/` — Cross-module integration tests (backlinks, tag filter, model download)
   - `tests/performance/` — Performance benchmarks
-  - Root-level `test_*_unit.py` files also exist (partial migration)
+  - Root-level `test_config_unit.py` and `test_config_set_unit.py` remain (no longer duplicated, test different things)
 - **pytest.ini**: `timeout=120`, `--strict-markers`, `-ra` (show all test summary)
 
 ## CI (GitHub Actions)
@@ -122,6 +125,8 @@ Four jobs in `.github/workflows/integration-test.yml`:
 - **Full** (manual): All tests, all OS, all Python versions
 - **Coverage** (after fast): Runs coverage on fast tests, uploads HTML/XML artifacts
 
+**Release** workflow in `.github/workflows/publish.yml`: publishes to PyPI on GitHub release publication.
+
 ## Windows Notes
 
 - `robocopy` flags get misinterpreted by bash — use `cmd.exe /c "robocopy source dest /E"`
@@ -135,4 +140,4 @@ Four jobs in `.github/workflows/integration-test.yml`:
 ## Gotchas
 
 - `pytest.ini` `addopts` includes `-v`, so `pytest tests/` already runs verbose — adding `-v` manually is redundant
-- Test directory migration is partial: root-level `test_*_unit.py` files duplicate `tests/unit/` tests
+- Test directory migration mostly complete; root-level `test_config_unit.py` and `test_config_set_unit.py` remain but test different things from `tests/unit/`

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 0.7.1
+Version: 0.7.2
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/jfox/__init__.py

@@ -1,5 +1,5 @@
 """JFox - Zettelkasten 知识管理工具"""
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"
 __author__ = "User"
 __email__ = "user@example.com"

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/jfox/cli.py

@@ -2,6 +2,7 @@
 
 import json
 import logging
+import re
 import sys
 import warnings
 from datetime import datetime
@@ -1146,8 +1147,25 @@ def delete(
         raise typer.Exit(1)
 
 
+def _strip_frontmatter(raw: str) -> str:
+    """如果内容包含 YAML frontmatter，则剥离 frontmatter 和标题行，只返回正文"""
+    # 去除 UTF-8 BOM
+    if raw.startswith(""):
+        raw = raw[1:]
+    match = re.match(r"^---\n.*?\n---\n+(.*)", raw, re.DOTALL)
+    if not match:
+        return raw
+    body = match.group(1).strip()
+    # 去除 jfox 生成的标题行（# 后跟空格和非空内容，空行结尾）
+    body = re.sub(r"^#[ \t]+\S.*\n*", "", body).strip()
+    return body
+
+
 def _read_content_file(content_file: str) -> str:
-    """从文件或 stdin 读取内容（--content-file 共用逻辑）"""
+    """从文件或 stdin 读取内容（--content-file 共用逻辑）
+
+    如果文件包含 YAML frontmatter（如 jfox 笔记文件），自动剥离只保留正文。
+    """
     if content_file == "-":
         import sys
 
@@ -1159,12 +1177,14 @@ def _read_content_file(content_file: str) -> str:
     if not p.is_file():
         raise ValueError(f"路径不是文件: {content_file}")
     try:
-        return p.read_text(encoding="utf-8")
+        raw = p.read_text(encoding="utf-8")
     except PermissionError:
         raise ValueError(f"无权限读取文件: {content_file}")
     except UnicodeDecodeError:
         raise ValueError(f"文件编码错误（需要 UTF-8）: {content_file}")
 
+    return _strip_frontmatter(raw)
+
 
 def _edit_impl(
     note_id: str,

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/jfox/note.py

@@ -1,6 +1,8 @@
 """笔记 CRUD 操作"""
 
 import logging
+import os
+import tempfile
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, List, Optional
@@ -59,15 +61,41 @@ def create_note(
     return note
 
 
+def _atomic_write(filepath: Path, content: str) -> None:
+    """原子写入：先写临时文件再原子替换，防止崩溃产生空文件"""
+    filepath.parent.mkdir(parents=True, exist_ok=True)
+    tmp_fd = -1
+    tmp_path = ""
+    try:
+        tmp_fd, tmp_path = tempfile.mkstemp(dir=filepath.parent, suffix=".tmp")
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            tmp_fd = -1  # fd 已移交 fdopen 管理
+            f.write(content)
+        # 保留目标文件权限（如已存在）
+        if filepath.exists():
+            try:
+                os.chmod(tmp_path, filepath.stat().st_mode)
+            except OSError:
+                pass
+        os.replace(tmp_path, filepath)
+    except BaseException:
+        if tmp_fd >= 0:
+            try:
+                os.close(tmp_fd)
+            except OSError:
+                pass
+        if tmp_path:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+        raise
+
+
 def save_note(note: Note, add_to_index: bool = True) -> bool:
     """保存笔记到文件"""
     try:
-        # 确保目录存在
-        note.filepath.parent.mkdir(parents=True, exist_ok=True)
-
-        # 写入文件
-        with open(note.filepath, "w", encoding="utf-8") as f:
-            f.write(note.to_markdown())
+        _atomic_write(note.filepath, note.to_markdown())
 
         logger.info(f"Saved note to {note.filepath}")
 
@@ -265,9 +293,7 @@ def update_note(note_obj: Note, add_to_index: bool = True) -> bool:
         note_obj.updated = datetime.now()
 
         # 写入新文件（filepath 属性根据当前字段生成）
-        note_obj.filepath.parent.mkdir(parents=True, exist_ok=True)
-        with open(note_obj.filepath, "w", encoding="utf-8") as f:
-            f.write(note_obj.to_markdown())
+        _atomic_write(note_obj.filepath, note_obj.to_markdown())
 
         # 如果文件路径变了（标题修改导致重命名），删除旧文件
         if old_filepath != note_obj.filepath and old_filepath.exists():

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/jfox/performance.py

@@ -9,6 +9,8 @@ import time
 from functools import wraps
 from typing import Any, Callable, List, Optional
 
+from .note import _atomic_write
+
 logger = logging.getLogger(__name__)
 
 
@@ -237,9 +239,7 @@ def bulk_import_notes(
             # 批量保存（不索引）
             for note in notes:
                 try:
-                    note.filepath.parent.mkdir(parents=True, exist_ok=True)
-                    with open(note.filepath, "w", encoding="utf-8") as f:
-                        f.write(note.to_markdown())
+                    _atomic_write(note.filepath, note.to_markdown())
                     imported += 1
                 except Exception as e:
                     logger.warning(f"Failed to save note: {e}")

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jfox-cli"
-version = "0.7.1"
+version = "0.7.2"
 description = "JFox - Zettelkasten 知识管理 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}

jfox_cli-0.7.2/tests/unit/test_atomic_write.py

@@ -0,0 +1,165 @@
+"""
+测试类型: 单元测试
+目标模块: jfox.note (_atomic_write 函数)
+预估耗时: < 1秒
+依赖要求: 无外部依赖
+"""
+
+import os
+import tempfile
+from unittest.mock import patch
+
+import pytest
+
+pytestmark = [pytest.mark.unit, pytest.mark.fast]
+
+from jfox.config import ZKConfig
+from jfox.models import NoteType
+from jfox.note import (
+    _atomic_write,
+    create_note,
+    find_note_file,
+    save_note,
+    update_note,
+)
+
+
+class TestAtomicWrite:
+    """测试 _atomic_write 原子写入"""
+
+    def test_normal_write(self, tmp_path):
+        """正常写入：文件内容正确"""
+        filepath = tmp_path / "test.md"
+        _atomic_write(filepath, "hello world")
+        assert filepath.read_text(encoding="utf-8") == "hello world"
+
+    def test_creates_parent_dir(self, tmp_path):
+        """目标目录不存在时自动创建"""
+        filepath = tmp_path / "sub" / "dir" / "test.md"
+        _atomic_write(filepath, "content")
+        assert filepath.read_text(encoding="utf-8") == "content"
+
+    def test_overwrites_existing(self, tmp_path):
+        """覆盖已有文件时内容正确"""
+        filepath = tmp_path / "test.md"
+        filepath.write_text("old content", encoding="utf-8")
+        _atomic_write(filepath, "new content")
+        assert filepath.read_text(encoding="utf-8") == "new content"
+
+    def test_no_tmp_file_on_write_failure(self, tmp_path):
+        """写入失败时不留临时文件，原文件不受影响"""
+        filepath = tmp_path / "test.md"
+        filepath.write_text("original", encoding="utf-8")
+
+        # 模拟写入过程中异常
+        with patch("os.replace", side_effect=OSError("disk full")):
+            with pytest.raises(OSError, match="disk full"):
+                _atomic_write(filepath, "new content")
+
+        # 原文件不受影响
+        assert filepath.read_text(encoding="utf-8") == "original"
+        # 无 .tmp 残留
+        tmp_files = list(tmp_path.glob("*.tmp"))
+        assert len(tmp_files) == 0
+
+    def test_no_empty_file_on_crash(self, tmp_path):
+        """崩溃后不会产生 0 字节目标文件"""
+        filepath = tmp_path / "test.md"
+        filepath.write_text("original", encoding="utf-8")
+
+        original_mkstemp = tempfile.mkstemp
+
+        def failing_mkstemp(**kwargs):
+            fd, path = original_mkstemp(**kwargs)
+            os.write(fd, b"partial")
+            os.close(fd)
+            raise KeyboardInterrupt
+
+        with patch("tempfile.mkstemp", side_effect=failing_mkstemp):
+            with pytest.raises(KeyboardInterrupt):
+                _atomic_write(filepath, "new content")
+
+        # 目标文件不受影响
+        assert filepath.read_text(encoding="utf-8") == "original"
+
+
+class TestUpdateNoteAtomic:
+    """测试 update_note 使用原子写入"""
+
+    def _make_config(self, tmp_path):
+        cfg = ZKConfig(base_dir=tmp_path)
+        cfg.ensure_dirs()
+        return cfg
+
+    @patch("jfox.note.config")
+    @patch("jfox.config.config")
+    def test_update_note_no_zero_byte_on_failure(
+        self, mock_global_config, mock_note_config, tmp_path
+    ):
+        """update_note 写入失败时不留 0 字节文件"""
+        cfg = self._make_config(tmp_path)
+        mock_global_config.notes_dir = cfg.notes_dir
+        mock_note_config.notes_dir = cfg.notes_dir
+
+        n = create_note("original", title="Test", note_type=NoteType.PERMANENT)
+        save_note(n, add_to_index=False)
+
+        # 修改内容
+        n.content = "modified"
+
+        # 模拟 _atomic_write 失败
+        with patch("jfox.note._atomic_write", side_effect=RuntimeError("boom")):
+            result = update_note(n, add_to_index=False)
+
+        assert result is False
+        # 磁盘上原文件不变
+        old_file = find_note_file(cfg, n.id)
+        assert old_file is not None
+        assert "original" in old_file.read_text(encoding="utf-8")
+
+
+class TestSaveNoteAtomic:
+    """测试 save_note 使用原子写入"""
+
+    def _make_config(self, tmp_path):
+        cfg = ZKConfig(base_dir=tmp_path)
+        cfg.ensure_dirs()
+        return cfg
+
+    @patch("jfox.note.config")
+    def test_save_note_uses_atomic_write(self, mock_config, tmp_path):
+        """save_note 应通过 _atomic_write 写入"""
+        cfg = self._make_config(tmp_path)
+        mock_config.notes_dir = cfg.notes_dir
+
+        n = create_note("test content", title="Test", note_type=NoteType.FLEETING)
+
+        with patch("jfox.note._atomic_write", wraps=_atomic_write) as mock_aw:
+            save_note(n, add_to_index=False)
+            mock_aw.assert_called_once()
+
+        # 验证文件内容正确
+        assert n.filepath.exists()
+        content = n.filepath.read_text(encoding="utf-8")
+        assert "test content" in content
+
+    @patch("jfox.note.config")
+    def test_save_note_no_zero_byte_on_failure(self, mock_config, tmp_path):
+        """save_note 写入失败时不留 0 字节文件"""
+        cfg = self._make_config(tmp_path)
+        mock_config.notes_dir = cfg.notes_dir
+
+        n = create_note("content", title="Test", note_type=NoteType.FLEETING)
+        n.set_filepath(cfg.notes_dir / "fleeting" / "test.md")
+
+        # 先创建一个有内容的文件
+        n.filepath.parent.mkdir(parents=True, exist_ok=True)
+        n.filepath.write_text("original content", encoding="utf-8")
+
+        # 模拟 _atomic_write 失败
+        with patch("jfox.note._atomic_write", side_effect=RuntimeError("boom")):
+            result = save_note(n, add_to_index=False)
+
+        assert result is False
+        # 原文件不受影响（不会被截断为 0 字节）
+        assert n.filepath.read_text(encoding="utf-8") == "original content"

jfox_cli-0.7.2/tests/unit/test_content_file.py

@@ -0,0 +1,73 @@
+"""测试 _read_content_file 对含 frontmatter 文件的处理"""
+
+import io
+import tempfile
+
+import pytest
+
+from jfox.cli import _read_content_file
+
+
+class TestReadContentFile:
+    """_read_content_file 的单元测试"""
+
+    def test_plain_content_unchanged(self):
+        """纯文本内容应原样返回"""
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".md", delete=False, encoding="utf-8"
+        ) as f:
+            f.write("Hello world")
+            f.flush()
+            result = _read_content_file(f.name)
+        assert result == "Hello world"
+
+    def test_content_with_frontmatter_stripped(self):
+        """含 frontmatter 的文件应只返回正文"""
+        raw = "---\nid: '123'\ntitle: test\n---\n\n# test\n\nBody text\n"
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".md", delete=False, encoding="utf-8"
+        ) as f:
+            f.write(raw)
+            f.flush()
+            result = _read_content_file(f.name)
+        assert "---" not in result
+        assert "Body text" in result
+
+    def test_content_with_frontmatter_no_title(self):
+        """含 frontmatter 但无标题行的文件"""
+        raw = "---\nid: '123'\ntitle: test\n---\n\nJust body text\n"
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".md", delete=False, encoding="utf-8"
+        ) as f:
+            f.write(raw)
+            f.flush()
+            result = _read_content_file(f.name)
+        assert "---" not in result
+        assert "Just body text" in result
+
+    def test_stdin_passthrough(self):
+        """stdin 模式（'-'）不应做处理"""
+        import sys
+
+        old_stdin = sys.stdin
+        try:
+            sys.stdin = io.StringIO("---\nid: x\n---\nbody")
+            result = _read_content_file("-")
+        finally:
+            sys.stdin = old_stdin
+        assert "---" in result
+
+    def test_file_not_found(self):
+        """不存在的文件应抛异常"""
+        with pytest.raises(ValueError, match="文件不存在"):
+            _read_content_file("/nonexistent/file.md")
+
+    def test_bom_file_stripped(self):
+        """含 UTF-8 BOM 的 frontmatter 文件应正确剥离"""
+        raw = "---\nid: '123'\ntitle: test\n---\n\nBody with BOM\n"
+        with tempfile.NamedTemporaryFile(mode="wb", suffix=".md", delete=False) as f:
+            f.write(raw.encode("utf-8-sig"))
+            f.flush()
+            result = _read_content_file(f.name)
+        assert "---" not in result
+        assert "Body with BOM" in result

{jfox_cli-0.7.1 → jfox_cli-0.7.2}/uv.lock

@@ -867,7 +867,7 @@ wheels = [
 
 [[package]]
 name = "jfox-cli"
-version = "0.7.1"
+version = "0.7.2"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },