task-ledger 1.3.0 → 1.3.2

package/scripts/ledgerkit/store/atomic.py

@@ -0,0 +1,130 @@
+"""怎么安全地写一个文件：唯一写盘出口。
+
+进门规则：不打印、不跑 git、不判断 owner/status、不自己加锁。
+写完顺手通知 `dirty` 记一笔（那是记账本唯一被写的地方之一）。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import stat
+import tempfile
+from pathlib import Path
+
+from ..errors import Fail
+from . import dirty
+
+
+def ensure_dir(path: Path) -> None:
+    """建目录（`mkdir -p` 语义）。**全仓唯一建目录的地方**，写文件不替人建父目录。"""
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        raise Fail(f"建目录 {path} 失败：{exc}") from exc
+
+
+def write_text_atomic(path: Path, text: str, *, track: bool = True) -> None:
+    """原子写文本：同目录临时文件 → 写 → fsync → 继承权限 → replace → fsync 父目录。
+
+    `track=False` 只给 `restore`（复原世界）与外壳两条受控通道用 —— 那三处都不是业务改动。
+    两个属性必须保住：mkstemp 建的是 0600，直接 replace 会把 644 降成 600；
+    符号链接一律拒绝，否则 replace 会把链接替换成普通文件。
+    """
+    fd = None
+    tmp: Path | None = None
+    existed = False
+    try:
+        # 不替调用方建父目录：建目录只有 ensure_dir 一处，业务层要自己先 ensure_dir
+        if not path.parent.exists():
+            raise Fail(
+                f"写 {path} 失败：父目录 {path.parent} 不存在（建目录要显式调 ensure_dir）。"
+            )
+        if path.is_symlink():
+            raise Fail(f"拒绝写入 {path}：它是符号链接，写入会把它替换成普通文件")
+        try:
+            mode = stat.S_IMODE(path.stat().st_mode)
+            existed = True
+        except OSError:
+            mode = 0o644  # 新文件：与 git 默认对齐
+        fd, tmp_name = tempfile.mkstemp(
+            dir=str(path.parent), prefix=path.name + ".", suffix=".tmp"
+        )
+        tmp = Path(tmp_name)
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
+            fd = None  # 所有权已交给文件对象
+            fh.write(text)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.chmod(tmp, mode)
+        os.replace(tmp, path)
+        _fsync_dir(path.parent)
+        tmp = None
+    except OSError as exc:
+        raise Fail(
+            f"写 {path} 失败：{exc}\n"
+            "  处理：确认该路径可写、磁盘没满，然后重跑这条命令（文件是整份替换，不会写坏）。"
+        ) from exc
+    finally:
+        if fd is not None:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        if tmp is not None and tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+    dirty.current().record(path, track=track, created=not existed)
+
+
+def _fsync_dir(dirpath: Path) -> None:
+    """刷父目录：掉电时 rename 的目录项可能丢，只刷文件是不够的。"""
+    try:
+        fd = os.open(str(dirpath), os.O_RDONLY)
+    except OSError:
+        return
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+    finally:
+        os.close(fd)
+
+
+def fingerprint(path: Path) -> str | None:
+    """文件内容 sha256，用来判「我读完以后别人动过没有」。
+
+    三种返回值互不相等：正常 → sha256 串；不存在 → None；读不了 → `"unreadable"`。
+    """
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        return None
+    except OSError:
+        return "unreadable"
+    return hashlib.sha256(data).hexdigest()
+
+
+def snapshot(path: Path) -> bytes | None:
+    """写之前把原文留一份字节；原本不存在返回 None。"""
+    try:
+        return path.read_bytes()
+    except FileNotFoundError:
+        return None
+    except OSError as exc:
+        raise Fail(f"读 {path} 失败：{exc}") from exc
+
+
+def restore(path: Path, before: bytes | None) -> None:
+    """按字节还原：`None` 表示原本不存在 ⇒ 删掉。恢复本身不进记账本（`track=False`）。"""
+    if before is None:
+        try:
+            path.unlink()
+        except FileNotFoundError:
+            return
+        except OSError as exc:
+            raise Fail(f"撤销 {path} 失败：{exc}") from exc
+        return
+    write_text_atomic(path, before.decode("utf-8"), track=False)

package/scripts/ledgerkit/store/dirty.py

@@ -0,0 +1,108 @@
+"""记账本：这一轮到底动了哪些文件。**提交集合只看它**，不看 `Result.changed`。
+
+三类记录各有各的用途：
+- `changed`：业务改动，最后要提交；
+- `created`：本次新建的文件，失败时要删掉（不能留下孤儿）；
+- `presync`：取最新时刷过的文件（连"刷之前"的字节一起）——它们**反而必须**一起提交，
+  否则拉下来的新内容留在工作树里，下一条写命令会被写前 guard 拦死。
+
+只返回清单、不打印（打印归外壳，否则 dirty 要 import shell，依赖反向）。
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass
+class WriteLog:
+    changed: list[Path] = field(default_factory=list)
+    created: list[Path] = field(default_factory=list)
+    presync: list[tuple[Path, bytes | None]] = field(default_factory=list)
+    # 进入提交阶段（_finalize 开始 git add/commit）后置位：此时台账数据已落盘，
+    # 失败 / 中断都不许回滚或删除 —— 那会吃掉刚写的台账（2026-10-24 修）。
+    commit_started: bool = False
+
+    def record(self, path: Path, *, track: bool = True, created: bool = False) -> None:
+        """记一次写。`track=False`（复原 / 外壳刷盘）不进改动集合。"""
+        if created and path not in self.created:
+            self.created.append(path)
+        if track and path not in self.changed:
+            self.changed.append(path)
+
+    def record_presync(self, path: Path, before: bytes | None) -> None:
+        """记「取最新刷过这个文件」+ 刷之前的字节（失败时按它恢复）。"""
+        for i, (known, _) in enumerate(self.presync):
+            if known == path:
+                self.presync[i] = (path, before)
+                return
+        self.presync.append((path, before))
+
+    def commit_set(self) -> list[Path]:
+        """最后要提交的文件：本次改动 + 取最新刷过的（去重保序）。"""
+        out: list[Path] = []
+        for path in [*self.changed, *(p for p, _ in self.presync)]:
+            if path not in out:
+                out.append(path)
+        return out
+
+    def has_writes(self) -> bool:
+        return bool(self.changed or self.presync)
+
+    def rollback_presync(self) -> list[Path]:
+        """按备份把「被取最新覆盖掉」的内容恢复回去（刷之前不存在 ⇒ 删掉）。"""
+        from .atomic import write_text_atomic
+
+        done: list[Path] = []
+        for path, before in reversed(self.presync):
+            if before is None:
+                try:
+                    path.unlink()
+                except FileNotFoundError:
+                    pass
+            else:
+                write_text_atomic(path, before.decode("utf-8"), track=False)
+            done.append(path)
+        self.presync = []
+        return done
+
+    def discard_created(self) -> list[Path]:
+        """删掉本次新建的文件（失败收尾用）。"""
+        done: list[Path] = []
+        for path in self.created:
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                pass
+            done.append(path)
+        self.created = []
+        return done
+
+    def clear(self) -> None:
+        """成功路径收尾：全部清零。"""
+        self.changed = []
+        self.created = []
+        self.presync = []
+
+
+_CURRENT: WriteLog = WriteLog()
+
+
+def current() -> WriteLog:
+    """当前这一轮的记账本（没绑定时给一个空账本）。"""
+    return _CURRENT
+
+
+@contextlib.contextmanager
+def bound(log: WriteLog) -> Iterator[None]:
+    """绑定这一轮的记账本（生产只在 runner 里绑一次；测试用）。"""
+    global _CURRENT
+    saved = _CURRENT
+    _CURRENT = log
+    try:
+        yield
+    finally:
+        _CURRENT = saved

package/scripts/ledgerkit/store/history_store.py

@@ -0,0 +1,189 @@
+"""已结案 `history/<年月>.md`：列全部文件、读一篇、算「追加一行后的新全文」、判重、落盘。
+
+「算」和「落」是两个方法 —— 结案要控顺序（历史 → 封卷 → 删分片），落盘时机由业务层定。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..core import history_md
+from ..core.paths import HISTORY_DIR, LEGACY_HISTORY_REL, to_repo_rel
+from .atomic import write_text_atomic
+from .worklog_store import WorklogStore
+
+HIT = "hit"
+MISS = "miss"
+UNDECIDABLE = "undecidable"
+
+
+class HistoryStore:
+    def __init__(self, repo: Path):
+        self.repo = Path(repo)
+
+    # ---- 读 ----
+
+    def sources(self) -> list[Path]:
+        """按月的 `history/*.md`（按文件名排序）+ 存量平铺文件（只读，永不重写）。"""
+        base = self.repo / to_repo_rel(HISTORY_DIR)
+        files = sorted(base.glob("*.md")) if base.is_dir() else []
+        legacy = self.repo / to_repo_rel(LEGACY_HISTORY_REL)
+        if legacy.is_file():
+            files.append(legacy)
+        return files
+
+    def month_key(self, path: Path) -> str:
+        """按月文件的 `YYYYMM`；存量平铺文件没有月份键，返回空串。"""
+        stem = Path(path).stem
+        return stem if len(stem) == 6 and stem.isdigit() else ""
+
+    def read(self, path: Path) -> str:
+        try:
+            return path.read_text(encoding="utf-8-sig")
+        except FileNotFoundError:
+            return ""
+        except OSError as exc:
+            raise ValueError(f"读 {path} 失败：{exc}") from exc
+
+    def _read_worklog(self, path: Path):
+        """升级要回链的 worklog 头部：读文件这件事留在 store，core 只消费返回的字典。"""
+        logs = WorklogStore(self.repo)
+
+        def read(log_name: str) -> dict[str, Any] | None:
+            found = logs.by_name(log_name)
+            return logs.head_meta(found) if found else None
+
+        return read
+
+    # ---- 判重 ----
+
+    def has_log(
+        self,
+        path: Path,
+        *,
+        log_name: str | None,
+        created: str | None,
+        title: str | None,
+    ) -> str:
+        """这个月的历史里已经有这条了吗？三态：`hit` / `miss` / `undecidable`。
+
+        有末列就比**文件名**（不比整条路径）。末列为空的行改按「创建时间 + 工作包」两列比
+        —— 那种行在调用方给不出 `created` / `title` 时判不了，明说 `undecidable`，不拿 miss 冒充。
+        """
+        records, _ = history_md.parse_history(self.read(path))
+        undecidable = False
+        for row in records:
+            worklog = (row.get("worklog") or "").strip()
+            if log_name and worklog:
+                if Path(worklog).name == Path(log_name).name:
+                    return HIT
+                continue
+            if not worklog:
+                if created and title:
+                    if row.get("created") == created and row.get("title") == title:
+                        return HIT
+                else:
+                    undecidable = True
+        return UNDECIDABLE if undecidable else MISS
+
+    # ---- 算 ----
+
+    def append_row(self, path: Path, row: dict[str, Any]) -> dict[str, Any]:
+        """算出「追加这一行后的新全文」，**不落盘**。
+
+        返回四个键：`text` / `upgraded` / `duplicate` / `fallback_cols`（`None` = 正常 9 列）。
+        老表列少又不敢整体升级时，按现有列数追加并让业务层提示，绝不硬写 9 列把表格挤歪。
+        """
+        original = self.read(path)
+        duplicate = (
+            self.has_log(
+                path,
+                log_name=_name_of(row.get("worklog")),
+                created=row.get("created"),
+                title=row.get("title"),
+            )
+            == HIT
+        )
+        if not original.strip():
+            text = _fresh_table()
+            upgraded = False
+            fallback_cols = None
+        else:
+            cols = history_md.history_cols(original)
+            if cols == 9:
+                text = original
+                upgraded = False
+                fallback_cols = None
+            else:
+                upgraded_text = history_md.upgrade_history(
+                    original,
+                    read_worklog=self._read_worklog(path),
+                    fallback_created=row.get("created") or "",
+                )
+                if upgraded_text is None:
+                    text = original
+                    upgraded = False
+                    fallback_cols = cols
+                else:
+                    text, _ = upgraded_text
+                    upgraded = True
+                    fallback_cols = None
+        line = (
+            history_md.history_line(
+                row.get("finished") or "",
+                row.get("created"),
+                row.get("title") or "",
+                row.get("owner"),
+                row.get("summary") or "",
+                row.get("worklog"),
+                row.get("category"),
+                row.get("tags"),
+                row.get("creator"),
+            )
+            if fallback_cols is None
+            else history_md.history_line_for_cols(
+                fallback_cols,
+                row.get("finished") or "",
+                row.get("created"),
+                row.get("title") or "",
+                row.get("owner"),
+                row.get("summary") or "",
+                row.get("worklog"),
+                row.get("category"),
+                row.get("tags"),
+                row.get("creator"),
+            )
+        )
+        return {
+            "text": _append_line(text, line),
+            "upgraded": upgraded,
+            "duplicate": duplicate,
+            "fallback_cols": fallback_cols,
+        }
+
+    # ---- 写 ----
+
+    def write(self, path: Path, text: str) -> None:
+        """历史表唯一的写回口：只用于「结案追加」与「8→9 列升级」的结果落盘。"""
+        write_text_atomic(path, text)
+
+
+def _name_of(worklog: str | None) -> str | None:
+    return Path(worklog).name if worklog else None
+
+
+def _fresh_table() -> str:
+    """当月第一次结案：按九列表头起表（表头的真源只有 `history_md` 一处）。"""
+    return (
+        f"{history_md.HISTORY_TITLE}\n\n"
+        f"{history_md.HISTORY_HEADER}\n{history_md.HISTORY_SEP}\n"
+    )
+
+
+def _append_line(text: str, line: str) -> str:
+    body = text.rstrip("\n")
+    if body and not body.splitlines()[-1].strip().startswith("|"):
+        # 表前有散文：补一个空行，别把表头贴上去
+        return body + "\n\n" + line
+    return body + "\n" + line

package/scripts/ledgerkit/store/json_store.py

@@ -0,0 +1,166 @@
+"""所有 JSON 台账的共用底座：读、按条取、按条写、按条删、指纹、一条一行的写盘格式。
+
+**版本字段的落点就在这里**：读盘发现与 `FORMAT_VERSION` 不符 ⇒ `notices.note` 一次（不拦）；
+写盘一律带上当前 `FORMAT_VERSION`（缺就补）。业务层各自判断就是散落。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from .. import notices
+from ..core.labels import FORMAT_VERSION
+from ..errors import Fail
+from .atomic import fingerprint, write_text_atomic
+
+
+def dump_ledger_json(data: dict[str, Any], *, expand: str = "tasks") -> str:
+    """「一条一行」的台账文本（`expand` 指定的那个字典一条一行，其余字段各占一行）。
+
+    键排序、值也 `sort_keys`：**同一份逻辑内容永远产出同一串字节** ——
+    多人各写各的才能按行合并，重写也不会产出无意义 diff。这是**格式契约**，
+    别改成缩进美化格式，也别按插入序输出（老文件会整篇翻面）。
+    """
+    body: dict[str, Any] = dict(data)
+    body["version"] = FORMAT_VERSION  # 写盘一律带当前版本（缺就补、旧就更新）
+    rows: list[str] = []
+    for key in sorted(body):
+        value = body[key]
+        if key == expand and isinstance(value, dict):
+            inner = [
+                f"    {json.dumps(k, ensure_ascii=False)}: "
+                f"{json.dumps(v, ensure_ascii=False, sort_keys=True)}"
+                for k, v in sorted(value.items())
+            ]
+            block = (",\n".join(inner) + "\n") if inner else ""
+            rows.append(f'  "{key}": {{\n{block}  }}')
+            continue
+        rows.append(
+            f'  "{key}": {json.dumps(value, ensure_ascii=False, sort_keys=True)}'
+        )
+    return "{\n" + ",\n".join(rows) + "\n}\n"
+
+
+def write_ledger_json(
+    path: Path, data: dict[str, Any], *, expand: str = "tasks"
+) -> None:
+    """按「一条一行」写台账（格式文本由 `dump_ledger_json` 出）。"""
+    write_text_atomic(path, dump_ledger_json(data, expand=expand))
+
+
+class JSONStore:
+    """一份 JSON 台账的读改写。首次读盘后缓存在实例里。"""
+
+    def __init__(self, path: Path, *, default: dict[str, Any], expand: str = "tasks"):
+        self.path = Path(path)
+        self.expand = expand
+        self._default = dict(default)
+        self._data: dict[str, Any] | None = None
+
+    # ---- 读 ----
+
+    def _load(self) -> dict[str, Any]:
+        if self._data is None:
+            data = self._read_raw()
+            if data is None:
+                # 文件还没有：按默认起一份，**不算版本不符**（没文件就没版本可比）
+                data = dict(self._default)
+                data["version"] = FORMAT_VERSION
+            else:
+                self._check_version(data)
+                rows = data.get(self.expand)
+                if rows is not None and not isinstance(rows, dict):
+                    # 版本不符只告警，但「tasks 不是对象」是读不了的真错（2026-10-22 数据契约）
+                    raise Fail(
+                        f"{self._rel()} 的 {self.expand} 不是对象"
+                        f"（是{type(rows).__name__}），这份台账读不了。\n"
+                        "  处理：用 git 恢复它（git checkout -- <文件>），或手工改成对象。"
+                    )
+            self._data = data
+        return self._data
+
+    def _read_raw(self) -> dict[str, Any] | None:
+        try:
+            text = self.path.read_text(encoding="utf-8-sig")
+        except FileNotFoundError:
+            return None
+        except OSError as exc:
+            raise ValueError(f"读 {self.path} 失败：{exc}") from exc
+        if not text.strip():
+            return None
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError(
+                f"{self.path} 不是合法 JSON（第 {exc.lineno} 行）：{exc.msg}"
+            ) from exc
+        if not isinstance(data, dict):
+            raise TypeError(f"{self.path} 顶层不是对象。")
+        return data
+
+    def _check_version(self, data: dict[str, Any]) -> None:
+        version = data.get("version")
+        if isinstance(version, str) and version == FORMAT_VERSION:
+            return
+        notices.note(
+            f"提示：{self._rel()} 的格式版本是 {version or '未知'}，"
+            f"当前是 {FORMAT_VERSION}；不拦，但字段可能有出入。"
+        )
+
+    def _rel(self) -> str:
+        try:
+            return self.path.name
+        except Exception:  # noqa: BLE001
+            return str(self.path)
+
+    def data(self) -> dict[str, Any]:
+        """整份只读视图（升级 / 体检用）。"""
+        return dict(self._load())
+
+    def get(self, key: str) -> dict[str, Any] | None:
+        value = self._load().get(self.expand, {}).get(key)
+        return dict(value) if isinstance(value, dict) else None
+
+    def all(self) -> dict[str, dict[str, Any]]:
+        rows = self._load().get(self.expand, {}) or {}
+        return {k: dict[str, Any](v) for k, v in rows.items() if isinstance(v, dict)}
+
+    def fingerprint(self) -> str | None:
+        return fingerprint(self.path)
+
+    # ---- 写 ----
+
+    def put(self, key: str, value: dict[str, Any]) -> None:
+        """改一条，其余原样保留。"""
+        data = self._load()
+        rows = data.setdefault(self.expand, {})
+        if not isinstance(rows, dict):
+            rows = {}
+            data[self.expand] = rows
+        rows[key] = dict(value)
+        self._flush(data)
+
+    def drop(self, key: str) -> None:
+        """删一条；本来就没有就什么都不做（不改变文件）。"""
+        data = self._load()
+        rows = data.get(self.expand, {})
+        if not isinstance(rows, dict) or key not in rows:
+            return
+        del rows[key]
+        self._flush(data)
+
+    def _flush(self, data: dict[str, Any]) -> None:
+        write_ledger_json(self.path, data, expand=self.expand)
+        self._data = data
+
+    def ensure_file(self) -> bool:
+        """文件不存在就按 `default` 写一份；存在就一个字节都不动。返回「这次建了没有」。"""
+        if self.path.exists():
+            return False
+        data = dict(self._default)
+        data.setdefault("version", FORMAT_VERSION)
+        write_ledger_json(self.path, data, expand=self.expand)
+        self._data = data
+        return True

package/scripts/ledgerkit/store/locks.py

@@ -0,0 +1,64 @@
+"""文件锁：只负责定义，**调用权归 actions/atom.py**（数据层禁止调用）。
+
+锁的不是目标文件本身：按绝对路径 hash 在系统临时目录开 `<hash>.lock` 再 flock。
+这样目标文件还不存在也能锁（锁集里本来就允许"还不存在"的路径），仓库里也不多出锁文件。
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import os
+import tempfile
+from collections.abc import Iterator
+from pathlib import Path
+
+from ..core.paths import to_repo_rel
+
+try:  # pragma: no cover —— 平台差异
+    import fcntl
+except ImportError:  # pragma: no cover
+    fcntl = None  # type: ignore[assignment]
+try:  # pragma: no cover
+    import msvcrt
+except ImportError:  # pragma: no cover
+    msvcrt = None  # type: ignore[assignment]
+
+
+@contextlib.contextmanager
+def progress_lock(path: Path) -> Iterator[None]:
+    """给一个台账文件加互斥锁：阻塞等待、没有超时、**不可重入**。"""
+    if fcntl is None and msvcrt is None:
+        yield
+        return
+    key = hashlib.sha256(str(path.resolve()).encode("utf-8")).hexdigest()[:16]
+    lock_path = Path(tempfile.gettempdir()) / f"koc-progress-{key}.lock"
+    fd = os.open(lock_path, os.O_CREAT | os.O_RDWR)
+    try:
+        if fcntl is not None:
+            fcntl.flock(fd, fcntl.LOCK_EX)
+        elif msvcrt is not None:
+            msvcrt.locking(fd, msvcrt.LK_LOCK, 1)  # type: ignore[attr-defined]
+        yield
+    finally:
+        try:
+            if fcntl is not None:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            elif msvcrt is not None:
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)  # type: ignore[attr-defined]
+        finally:
+            os.close(fd)
+
+
+@contextlib.contextmanager
+def ledger_lock(repo: Path, *rels: Path) -> Iterator[None]:
+    """多个文件一起锁：去重 → 按路径排序 → 依次加（避免两人互相等死）。"""
+    # rels 相对 `ledger/`（与磁盘 / JSON 同一基准），换算只走 to_repo_rel
+    paths = sorted({(repo / to_repo_rel(rel)) for rel in rels}, key=lambda p: str(p))
+    if not paths:
+        yield
+        return
+    with contextlib.ExitStack() as stack:
+        for path in paths:
+            stack.enter_context(progress_lock(path))
+        yield