task-ledger 1.3.0 → 1.3.1

package/scripts/ledgerkit/store/owners_index.py

@@ -0,0 +1,135 @@
+"""索引 `owners.json`：谁是登记过的人、各自的分片文件是哪个、新人的登记与改名。
+
+**分片只认索引，不扫目录** —— 唯一例外是全仓仅此一处的 `disk_shards()`，它只给 `validate` 用。
+`ensure` 是 `aliases` 的唯一写入点。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Self
+
+from ..core.identity import Identity, normalize
+from ..core.paths import OWNERS_DIR, OWNERS_REL, shard_rel, to_repo_rel
+from ..core.time import now
+from ..errors import Fail
+from .json_store import JSONStore
+
+DEFAULT_DATA = {"version": "", "workers": {}}
+
+
+class OwnersIndex:
+    def __init__(self, repo: Path):
+        self.repo = Path(repo)
+        self._store = JSONStore(
+            self.repo / to_repo_rel(OWNERS_REL), default=DEFAULT_DATA, expand="workers"
+        )
+
+    def get(self, who: str) -> dict[str, Any] | None:
+        return self._store.get(normalize(who))
+
+    def all(self) -> dict[str, dict[str, Any]]:
+        return self._store.all()
+
+    def ensure(self, me: Identity) -> tuple[bool, dict[str, Any]]:
+        """登记 / 补 `joined` / 名字或 aliases 变了才写。返回 (这次写了没有, 记录)。"""
+        key = normalize(me.email)
+        with self._open() as session:
+            data = session.data
+            workers = data.setdefault("workers", {})
+            record = workers.get(key)
+            if record is None:
+                record = {
+                    "file": shard_rel(key).name,
+                    "name": me.name,
+                    "joined": now(),
+                    "aliases": _merge_aliases([], me.aliases),
+                }
+                workers[key] = record
+                session.mark()
+                return True, dict(record)
+            changed = False
+            if me.name and record.get("name") != me.name:
+                record["name"] = me.name
+                changed = True
+            known = list(record.get("aliases") or [])
+            aliases = _merge_aliases(known, me.aliases)  # 只增不删
+            if aliases != known:
+                record["aliases"] = aliases
+                changed = True
+            if changed:
+                session.mark()
+            return changed, dict(record)
+
+    def shards(self) -> dict[str, Path]:
+        """身份 → 分片绝对路径（只信索引）。"""
+        out: dict[str, Path] = {}
+        for key, record in self.all().items():
+            name = (record or {}).get("file")
+            if not name:
+                continue
+            out[key] = self.repo / to_repo_rel(OWNERS_DIR) / str(name)
+        return out
+
+    def disk_shards(self) -> list[Path]:
+        """扫 `owners/` 下的全部 `*.json`。**全仓唯一扫目录的地方**，只给 `validate`。"""
+        base = self.repo / to_repo_rel(OWNERS_DIR)
+        if not base.is_dir():
+            return []
+        return sorted(p for p in base.glob("*.json") if p.is_file())
+
+    def assert_present(self) -> None:
+        """登记过的分片（含池）文件必须都在；被人删了/改名了就报清楚，绝不悄悄当空、绝不修复。
+
+        只校验「该在的文件在不在」，不碰内容、不重建。本方法只在校读路径
+        （list / show / validate）调用；会新建分片的写动作（claim/set/…）里不调，
+        否则全新仓库第一次写会被误报「分片文件缺失」。
+        """
+        missing = [str(p) for p in self.shards().values() if not p.exists()]
+        if missing:
+            raise Fail(
+                "台账里登记的任务文件找不到了（可能被人手动删除或改名）：\n  "
+                + "\n  ".join(missing)
+                + "\n程序不自动修复——请用 git 恢复原文件（git checkout -- <文件>），"
+                "或把原文件放回原处，再重试。"
+            )
+        # 索引本身没了、但盘上还有分片 ⇒ 分片变成无主孤儿，等同于被删
+        if not (self.repo / to_repo_rel(OWNERS_REL)).exists() and self.disk_shards():
+            raise Fail(
+                "台账索引 owners.json 找不到了，但 owners/ 下还有任务文件"
+                "（可能被人手动删除或改名）。\n程序不自动修复——请用 git 恢复 owners.json，再重试。"
+            )
+
+    def _open(self):
+        """把 `ensure` 的读写收在一处：任何改动最终都按一条一行写回。"""
+        return _IndexSession(self._store)
+
+
+class _IndexSession:
+    """索引的一次读写：**没改动就不写回**（自举要能零写，否则每次都撞「nothing to commit」）。"""
+
+    def __init__(self, store: JSONStore):
+        self.store = store
+        self.data: dict[str, Any] = {}
+        self.changed = False
+
+    def mark(self) -> None:
+        self.changed = True
+
+    def __enter__(self) -> Self:
+        self.data = self.store.data()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        if self.changed:
+            self.store._flush(self.data)  # 同一个包内的受控写回口
+
+
+def _merge_aliases(known: list, extra: tuple[str, ...] | list[str]) -> list[str]:
+    """把新别名并进去，只增不删、去重保序。"""
+    out = list(known)
+    for alias in extra or ():
+        key = normalize(alias)
+        if key and key not in out:
+            out.append(key)
+    return out

package/scripts/ledgerkit/store/task_store.py

@@ -0,0 +1,31 @@
+"""任务表：公共池 `pool.json` 与某人的分片 `owners/<hash>.json` —— **同一个类，只是路径不同**。
+
+`identity` 只用于**写盘格式**（分片顶部的可选 `identity` 字段），它不参与任何判断：
+不判归属、不改 `updated`、不判状态 —— 那些归 `actions/guard.py`。构造**不写盘**。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..core.identity import Identity
+from ..core.paths import to_repo_rel
+from .json_store import JSONStore
+
+DEFAULT_DATA = {"version": "", "tasks": {}}
+
+
+class TaskStore(JSONStore):
+    def __init__(self, repo: Path, rel: Path, *, identity: Identity | None = None):
+        super().__init__(Path(repo) / to_repo_rel(rel), default=DEFAULT_DATA)
+        self.identity = identity
+
+    def _flush(self, data: dict[str, Any]) -> None:
+        """写盘时带上分片顶部的 `identity`（只改格式，不动任务内容）。"""
+        if self.identity is not None:
+            data["identity"] = {
+                "email": self.identity.email,
+                "name": self.identity.name,
+            }
+        super()._flush(data)

package/scripts/ledgerkit/store/worklog_store.py

@@ -0,0 +1,168 @@
+"""过程文档 `worklog/<年月>/*.md`：找一篇、读、列全部、建新篇、写回、追加执行记录。
+
+模板的**读取**在这里（`template()` 是全仓唯一读 `assets/worklog.md` 的地方），
+套模板的字符串替换归 `core/worklog_md.render_worklog`。
+写回只走「锚点编辑后的新全文」，不许用它替换前五节正文。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .. import notices
+from ..core import worklog_md
+from ..core.paths import (
+    WORKLOG_DIR,
+    WORKLOG_TEMPLATE,
+    to_repo_rel,
+    worklog_name,
+    worklog_rel,
+)
+from .atomic import ensure_dir, write_text_atomic
+
+FALLBACK_TEMPLATE = """# <id>：<title>
+
+> **创建**：<created>（@<creator>）
+
+## 背景
+
+## 待办
+
+## 下一步
+
+## 过程
+
+## 结论
+
+## 执行记录
+
+<!-- 本节由脚本维护：new / claim / set / release / log / close 自动追加，请勿手改。 -->
+"""
+
+
+class WorklogStore:
+    def __init__(self, repo: Path):
+        self.repo = Path(repo)
+
+    # ---- 模板 ----
+
+    def template(self) -> str:
+        """六节模板：读不到 `assets/worklog.md` → 内置骨架 + 一条提示。"""
+        try:
+            if WORKLOG_TEMPLATE.exists():
+                return WORKLOG_TEMPLATE.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            pass
+        notices.note(
+            "提示：读不到模板 assets/worklog.md，本次用内置骨架建篇（六节齐全，正文仍是空的）。"
+        )
+        return FALLBACK_TEMPLATE
+
+    # ---- 找 ----
+
+    def find(self, tid: str, worklog_rel_value: str | None = None) -> Path | None:
+        """定位一篇过程文档：先信任务对象里记的路径，再按命名推算，最后扫目录。"""
+        if worklog_rel_value:
+            cand = self.repo / to_repo_rel(worklog_rel_value)
+            if cand.is_file():
+                return cand
+        base = self.repo / to_repo_rel(WORKLOG_DIR)
+        names = (worklog_name(tid), f"{tid}.md")
+        dirs = [base]
+        if base.is_dir():
+            dirs += sorted(d for d in base.iterdir() if d.is_dir())
+        for directory in dirs:
+            for name in names:
+                cand = directory / name
+                if cand.is_file():
+                    return cand
+        return None
+
+    def by_name(self, log_name: str) -> Path | None:
+        """按文件名找（历史末列回链用）。"""
+        base = self.repo / to_repo_rel(WORKLOG_DIR)
+        if not base.is_dir():
+            return None
+        direct = base / log_name
+        if direct.is_file():
+            return direct
+        for path in sorted(base.rglob(log_name)):
+            if path.is_file():
+                return path
+        return None
+
+    def all(self) -> list[Path]:
+        """递归列出全部过程文档。"""
+        base = self.repo / to_repo_rel(WORKLOG_DIR)
+        if not base.is_dir():
+            return []
+        return sorted(p for p in base.rglob("*.md") if p.is_file())
+
+    # ---- 读 ----
+
+    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 head_meta(self, path: Path) -> dict[str, Any]:
+        """头部四样：`created` / `creator` / `category` / `tags`；读不出给空值。"""
+        text = self.read(path)
+        category, tags = worklog_md.head_meta(text)
+        return {
+            "created": worklog_md.head_created(text),
+            "creator": worklog_md.head_creator(text),
+            "category": category,
+            "tags": list(tags),
+        }
+
+    # ---- 写 ----
+
+    def create(
+        self,
+        *,
+        tid: str,
+        title: str,
+        created: str,
+        creator: str,
+        category: str | None = None,
+        tags: tuple[str, ...] = (),
+        first_exec: str | None = None,
+    ) -> Path:
+        """一次写完整篇（含首条执行记录）。返回绝对路径。"""
+        rel = worklog_rel(tid, created)
+        path = self.repo / to_repo_rel(rel)
+        ensure_dir(path.parent)
+        text = worklog_md.render_worklog(
+            tid=tid,
+            title=title,
+            created=created,
+            creator=creator,
+            category=category,
+            tags=tags,
+            template=self.template(),
+        )
+        if first_exec:
+            text = worklog_md.append_exec_log(text, first_exec)
+        write_text_atomic(path, text)
+        return path
+
+    def write(self, path: Path, text: str) -> None:
+        """写回「锚点编辑后的新全文」；不许用它替换前五节正文。"""
+        write_text_atomic(path, text)
+
+    def append_exec(self, path: Path, line: str) -> bool:
+        """追加一条执行记录；写不进返回 False，**不抛**（调用方自己决定报不报）。"""
+        try:
+            text = path.read_text(encoding="utf-8-sig")
+        except (OSError, UnicodeDecodeError):
+            return False
+        try:
+            write_text_atomic(path, worklog_md.append_exec_log(text, line))
+        except Exception:  # noqa: BLE001 —— 写不进是这条记录的失败，不该掀翻整条命令
+            return False
+        return True