dsh-task-ledger 0.0.101 → 0.0.102

package/skill/scripts/ledgerkit/store/json_store.py

@@ -1,166 +0,0 @@
-"""所有 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/skill/scripts/ledgerkit/store/locks.py

@@ -1,64 +0,0 @@
-"""文件锁：只负责定义，**调用权归 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

package/skill/scripts/ledgerkit/store/owners_index.py

@@ -1,127 +0,0 @@
-"""索引 `owners.json`：谁是登记过的人、各自的分片文件是哪个、新人的登记与改名。
-
-**分片只认索引，不扫目录** —— 唯一例外是全仓仅此一处的 `disk_shards()`，它只给 `validate` 用。
-"""
-
-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`。`name` 只在首次登记时写入，之后不回写（名字是给你做对照的被动字段，不该被任何逻辑读）。返回 (这次写了没有, 记录)。"""
-        key = normalize(me.uuid)
-        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(),
-                }
-                workers[key] = record
-                session.mark()
-                return True, dict(record)
-            return False, dict(record)
-
-    def keys_of_name(self, fragment: str) -> set[str]:
-        """显示名模糊匹配（不分大小写的子串）⇒ uuid 集合。**只给查询筛选**，不参与归属判定。
-
-        比对的是名册里的名字（`workers[<uuid>].name`），不是每条任务上那份冗余的
-        `owner_name`：改名后名册先变，筛选结果跟着变，任务里的旧名字不会干扰。
-        """
-        needle = normalize(fragment)
-        if not needle:
-            return set()
-        return {
-            key
-            for key, record in self.all().items()
-            if needle in normalize(str((record or {}).get("name") or ""))
-        }
-
-    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)  # 同一个包内的受控写回口

package/skill/scripts/ledgerkit/store/task_store.py

@@ -1,28 +0,0 @@
-"""任务表：公共池 `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`（只存 uuid；显示名在索引里）。"""
-        if self.identity is not None:
-            data["identity"] = {"uuid": self.identity.uuid}
-        super()._flush(data)

package/skill/scripts/ledgerkit/store/worklog_store.py

@@ -1,178 +0,0 @@
-"""过程文档 `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>
-
-- **状态**：<status>
-- **创建**：<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,
-        tags: tuple[str, ...] = (),
-        status: worklog_md.StatusLine | None = None,
-        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,
-            tags=tags,
-            status=status,
-            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, *, status: worklog_md.StatusLine | None = None
-    ) -> bool:
-        """追加一条执行记录，并在**同一次写盘**里顺带刷新头部状态行（`status` 给了才刷）。
-
-        写不进返回 False，**不抛**（调用方自己决定报不报）。状态行与执行记录必须一起落地：
-        分两写就会留下「记录写了、状态没刷」这种不报错的不一致。
-        """
-        try:
-            text = path.read_text(encoding="utf-8-sig")
-        except (OSError, UnicodeDecodeError):
-            return False
-        try:
-            new = worklog_md.append_exec_log(text, line)
-            if status is not None:
-                new = worklog_md.rewrite_status_line(new, status)
-            write_text_atomic(path, new)
-        except Exception:  # noqa: BLE001 —— 写不进是这条记录的失败，不该掀翻整条命令
-            return False
-        return True

package/skill/scripts/progress.py

@@ -1,20 +0,0 @@
-#!/usr/bin/env python3
-"""程序入口：只做四件事，业务逻辑一行都不在这里。
-
-1. 关掉字节码（本脚本会被 cp -r 拷进插件产物，不能带 __pycache__）；
-2. 把自己所在目录塞进 sys.path（宿主与 SKILL.md 都按这个路径调，不许改名挪位）；
-3. 调 ledgerkit.shell.cli.main；
-4. 把返回码交给系统。
-"""
-
-import os
-import sys
-
-sys.dont_write_bytecode = True
-
-sys.path.insert(0, os.path.dirname(os.path.realpath(__file__)))
-
-from ledgerkit.shell.cli import main
-
-if __name__ == "__main__":
-    sys.exit(main())